Reference

Troubleshooting

What each SignatureAPI CLI failure code means and how to fix it.

When a command fails, the CLI prints a failure code, and a next step whenever you can fix the cause yourself. With --json, the code is the code field of the final result event, and the next step is in next_actions. The next step the CLI prints is authoritative for the version you run; this page explains the codes you are most likely to see.

To report a problem, include the command, the failure code, and the CLI version (npx signatureapi --version). Never include API keys, signing secrets, or the contents of your env file.

Sign-in

CodeCauseFix
authorization-requiredThere is no sign-in, and the command does not start one (whoami).Run npx --yes signatureapi login.
authorization-expiredThe sign-in code expired before it was approved.Run the command again and approve the new code.
authorization-deniedThe sign-in was denied in the browser.Run the command again and approve it.
authorization-canceledYou stopped the command while it waited for approval.Run the command again.
authorization-failed, oauth-configuration-invalid, oauth-response-invalidThe stored sign-in could not be refreshed. It is kept.Run npx --yes signatureapi login to sign in again.
oauth-network-errorThe CLI could not reach the sign-in service. The stored sign-in is kept.Check your network connection or proxy, then try again.
invalid-cli-tokenThe sign-in is no longer valid.Run logout, then login.
cli-authorization-revokedThe sign-in was revoked.Run logout, then login.
cli-scope-requiredThe sign-in lacks the permissions the CLI requests.Run logout, then login, and approve every requested permission.
cli-account-not-readyThe organization you chose has no SignatureAPI account the CLI can use.Sign in again and choose another organization, or finish setting up the account in the Dashboard.
credential-store-unavailableThe chosen credential store cannot be used.Without a usable OS keychain, pass --credential-store file. If the file store fails, check that its directory belongs to you and is writable. See Where the sign-in is stored.

Live mode and permissions

CodeCauseFix
live-mode-unavailableThe account cannot act in live mode: it is not active, or your organization role does not grant live-mode access.Use test mode, or activate the account in the Dashboard.
cli-key-limit-reachedThe account already has five active API keys.Revoke a live key you no longer use (api-keys list, then api-keys revoke), or roll an existing key instead.
confirmation-requiredA live-key change needs confirmation, and the shell cannot prompt. Nothing changed.Pass --yes.
confirmation-declinedYou declined the confirmation prompt. Nothing changed.Run the command again and confirm, if you meant to make the change.

Env files

These codes come from the env file rules. In every case the CLI leaves the file unchanged.

CodeCauseFix
credential-conflictThe variable already holds a different key.Check that you chose the right --var and --env-path. Pass --replace only when you mean to replace the value.
mode-mismatchThe variable holds a key of the other mode.Use another --var or --env-path for this mode.
webhook-id-conflictThe env file holds a different webhook ID.Use that ID, choose another --webhook-id-var or --env-path, or pass --replace to listen to switch it.
env-trackedGit tracks the env file.Remove it from Git tracking (git rm --cached <file>), then try again.
env-not-ignoredGit does not ignore the env file.Add it to .gitignore, and remove any rule that un-ignores it (such as !.env).
ignore-file-invalidThe CLI could not read or update .gitignore.Make .gitignore a regular file you can write, not a symbolic link or directory.
env-lockedAnother signatureapi command is writing the same env file.Wait for it to finish, then try again.
env-changedThe env file changed while the command was writing it.Try again.
env-permissions-unsafeYou don’t own the env file.Make the file yours, then try again.
invalid-env-path--env-path points outside the current directory.Run the command from your application’s directory, and choose a file inside it.
reserved-env-path--env-path names package.json, .gitignore, or a path inside .git.Choose another file.
env-parent-missingThe env file’s directory does not exist.Create the directory, then try again.
env-target-invalid, unsafe-pathThe env file is a directory, a symbolic link, or another non-regular file.Choose a regular file inside your application’s directory.
ambiguous-assignmentThe env file assigns the variable more than once.Keep one assignment, then try again.
unsupported-env-syntaxThe variable’s current value is quoted or continues onto the next line, or the file is not UTF-8. The CLI only edits plain NAME=value lines.Write the value without quotes, or remove the line and let the CLI write it.
duplicate-variable, invalid-webhook-selectionTwo values were given the same env variable.Choose a different variable for each value.

Webhooks

CodeCauseFix
secondary-secret-requiredYou chose a second webhook ID but kept the default secret variable.Pass --secret-var for the second webhook, or use another --env-path. See Run more than one endpoint.
invalid-options with a --webhook-id messageThe value is not a CLI webhook ID.Pass the cli_ ID that listen saved, not an ID from another tool.
tunnel-start-failed, or another tunnel codeThe temporary tunnel for --forward-to could not start. The code names the step that failed: downloading the tunnel client, checking it, using its cache directory, or waiting for the tunnel.Follow the next step the CLI prints. Check your network connection or proxy and try again, or deliver to a public HTTPS URL you run with --public-url.

When the tunnel works but deliveries fail, the listener reports webhook_forward_failed per delivery, not a failure code. Its reason says why: handler_unreachable (nothing answered at --forward-to), handler_timeout (your handler took longer than 30 seconds), or delivery_closed. Check that your handler is running at the URL you passed.

Usage

CodeCauseFix
invalid-optionsAn unknown command or option, a missing argument, or an invalid value. The message says which, and suggests a spelling when it can.Run the --help command the next step names.
invalid-description--description is longer than 255 characters.Shorten it.

Usage failures exit with code 2. See Exit codes.

Service and network

CodeCauseFix
cli-network-errorThe CLI could not reach SignatureAPI.Check your network connection or proxy, then try again.
too-many-requestsToo many requests in a short time.Wait a minute, then try again.
cli-service-unavailable, cli-provider-unavailable, cli-authorization-unavailableA SignatureAPI service is temporarily unavailable.Try again in a few minutes. Check the status page.
cli-disabledThe CLI service is turned off.Try again later, or contact support.
cli-http-<status>SignatureAPI answered with an HTTP status the CLI has no code for.Try again. If it persists, contact support with the status.
command-failedAn unexpected failure.Try again. If it persists, contact support with the command and the CLI version.

Results that need attention

Some partial results are not failures, but they ask you to check something:

  • credentials_write_failed: a key was created or rolled, but the CLI could not write it to the env file. The result names the key ID and how to recover.
  • key_creation_unconfirmed, key_roll_unconfirmed: the CLI cannot tell whether the change happened, for example after a timeout. Run api-keys list before you try again. The CLI never retries these on its own.
  • listener_cleanup_unavailable: the listener could not confirm it disabled the webhook endpoint. Check it in the Dashboard’s Webhooks settings, or run listen again.
  • logout_revocation_unconfirmed: the local sign-in was removed, but the revocation could not be confirmed.