Troubleshooting

Encountering issues with ZKsync CLI? Here are some common problems and step-by-step recommendations for resolving them:

command not found: zksync-cli

If you try to use the zksync-cli command and receive the command not found message, double check if you have the package installed locally or were using the npx zksync-cli command.

unknown command Error

If you encounter an unknown command error, follow these steps:

a. Check the ZKsync CLI Version

• Run zksync-cli --version to check your current version.
• Compare it with the latest version available on npm.
• If your version is lower than the one on npm, follow the steps below. If your version is up-to-date, it's possible that the command was moved or renamed. Use zksync-cli help for a list of current commands or refer to the documentation.

b. Verify Local Installation

• Use npm list zksync-cli to check if zksync-cli is installed in the current directory or any parent directories from where you are running your terminal.
• If it is indeed installed, make sure to uninstall it by running npm uninstall zksync-cli in its installation location. Remove all instances of zksync-cli until none are found by npm list zksync-cli.

c. Verify Global Installation

• Use npm list -g zksync-cli to check if zksync-cli is installed globally.
• If it is installed globally, uninstall it using npm uninstall -g zksync-cli.

d. Clean npm Cache

• Run npm cache clean --force.

e. Use the Latest Version

• As a quick fix, or if the above steps don't resolve the issue, use npx zksync-cli@latest [command], for example, npx zksync-cli@latest dev start.

My version is outdated

If zksync-cli is not running the latest version:

• Refer to the instructions for unknown command Error above to check and update your ZKsync CLI version.

command not found: npx Error

If you receive a command not found: npx error, it means Node.js is not installed or not correctly set up on your system:

• Install Node.js from the official website. This will also install npm and npx.
• After installation, restart your terminal and try running npx zksync-cli again.

Other issues

For all other issues, we encourage you to seek help or report them in our GitHub Discussions.