Troubleshooting
Common CLI errors and first checks.
Local server is not running
console reports E_LOCAL_SERVER_NOT_RUNNING when the local runtime is stopped, and so do the commands that call the platform, such as setup, deploy, or variable, when run with --server local. Without the flag, they use the server the environment resolves (ZITADEL_URL), so against a stopped local server they fail with E_NETWORK (ECONNREFUSED). In each case, start the local runtime again from the directory you first ran start in (the one with .zitadel/local/):
npx @zitadel/cli@latest startThen retry the command.
Port is in use
If start or doctor reports E_PORT_IN_USE, the runtime port already has a listener. If it is a runtime the CLI started earlier with the default binary backend, possibly in another directory, stop all of those (macOS and Linux only):
npx @zitadel/cli@latest stop --allstop --all does not stop a Docker runtime; run stop in the directory that runtime was started from. Otherwise, stop the process that holds the port, or choose another port:
npx @zitadel/cli@latest start --port 8081JSON output looks mixed with installer logs
Capture stdout and stderr separately. The JSON envelope is on stdout; package-manager progress belongs on stderr.
Browser proof stops at the form
A rendered login or registration form is not enough. Complete registration, logout, login, and signed-in profile verification in a real browser.
Old localhost passkeys still appear
Browser and OS passkeys for localhost can outlive zitadel reset --force, deleted app folders, and new local projects. If the passkey picker shows stale local accounts, remove the old localhost passkeys from your browser or operating system credential manager.
Password managers can also keep their save or update sheet open after the app redirects to the signed-in profile. An Update Existing prompt usually means the manager found an old localhost item with the same account label. Update it, save a new item, or delete the stale local passkey before retrying.
Was this helpful?