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
| Code | Cause | Fix |
|---|---|---|
authorization-required | There is no sign-in, and the command does not start one (whoami). | Run npx --yes signatureapi login. |
authorization-expired | The sign-in code expired before it was approved. | Run the command again and approve the new code. |
authorization-denied | The sign-in was denied in the browser. | Run the command again and approve it. |
authorization-canceled | You stopped the command while it waited for approval. | Run the command again. |
authorization-failed, oauth-configuration-invalid, oauth-response-invalid | The stored sign-in could not be refreshed. It is kept. | Run npx --yes signatureapi login to sign in again. |
oauth-network-error | The 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-token | The sign-in is no longer valid. | Run logout, then login. |
cli-authorization-revoked | The sign-in was revoked. | Run logout, then login. |
cli-scope-required | The sign-in lacks the permissions the CLI requests. | Run logout, then login, and approve every requested permission. |
cli-account-not-ready | The 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-unavailable | The 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
| Code | Cause | Fix |
|---|---|---|
live-mode-unavailable | The 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-reached | The 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-required | A live-key change needs confirmation, and the shell cannot prompt. Nothing changed. | Pass --yes. |
confirmation-declined | You 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.
| Code | Cause | Fix |
|---|---|---|
credential-conflict | The 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-mismatch | The variable holds a key of the other mode. | Use another --var or --env-path for this mode. |
webhook-id-conflict | The 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-tracked | Git tracks the env file. | Remove it from Git tracking (git rm --cached <file>), then try again. |
env-not-ignored | Git does not ignore the env file. | Add it to .gitignore, and remove any rule that un-ignores it (such as !.env). |
ignore-file-invalid | The CLI could not read or update .gitignore. | Make .gitignore a regular file you can write, not a symbolic link or directory. |
env-locked | Another signatureapi command is writing the same env file. | Wait for it to finish, then try again. |
env-changed | The env file changed while the command was writing it. | Try again. |
env-permissions-unsafe | You 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-missing | The env file’s directory does not exist. | Create the directory, then try again. |
env-target-invalid, unsafe-path | The env file is a directory, a symbolic link, or another non-regular file. | Choose a regular file inside your application’s directory. |
ambiguous-assignment | The env file assigns the variable more than once. | Keep one assignment, then try again. |
unsupported-env-syntax | The 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-selection | Two values were given the same env variable. | Choose a different variable for each value. |
Webhooks
| Code | Cause | Fix |
|---|---|---|
secondary-secret-required | You 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 message | The 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 code | The 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
| Code | Cause | Fix |
|---|---|---|
invalid-options | An 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
| Code | Cause | Fix |
|---|---|---|
cli-network-error | The CLI could not reach SignatureAPI. | Check your network connection or proxy, then try again. |
too-many-requests | Too many requests in a short time. | Wait a minute, then try again. |
cli-service-unavailable, cli-provider-unavailable, cli-authorization-unavailable | A SignatureAPI service is temporarily unavailable. | Try again in a few minutes. Check the status page. |
cli-disabled | The 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-failed | An 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. Runapi-keys listbefore 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 runlistenagain.logout_revocation_unconfirmed: the local sign-in was removed, but the revocation could not be confirmed.