Reference
Errors and troubleshooting
Grouped by what you should do, not by where the message came from. If a situation is not listed here, it is because we have not observed it.
While scanning
| Symptom | What it means | Do |
|---|---|---|
| Exit 3, entry not found | No entry came back. It may never have existed, or it may already be archived. | Check whether it was archived. Restore before extending — an archived entry cannot be extended in place. |
| Exit 3, TTL unavailable | The entry exists but no TTL metadata came back. | Retry. Treat it as unknown, not as healthy, until a reading succeeds. |
| Exit 3 with --require-declared-scope | Neither --keys-file nor --no-data-keys was given, so storage was not covered. | Declare the scope. On a contract you own, this is a gap rather than a caveat. |
| Exit 2, RPC failure | The network refused or was unreachable. The check did not run. | Retry, and check the rpcUrl. This is not a health result. |
| Sharing reads UNDETERMINED | Not an error. One contract cannot reveal the others that share its code entry. | Pass the contracts together. The answer is still a lower bound. |
While extending
| Symptom | What it means | Do |
|---|---|---|
| Simulation succeeded but nothing changed | Expected. Simulation is the default and does not submit. | Add --submit with a secret variable name and a fee cap when you mean it. |
| “there is no fallback payer” | No payer was supplied. | Pass --source-account or set EVERGREEN_SOURCE_ACCOUNT. The tool will not pick one. |
| “the secret does not match the expected source account” | The key in the named variable does not control the payer you named. | Reconfigure. This is distinguished from a malformed secret on purpose — they are different operator actions. |
| Target was capped | Your requested target exceeded max_entry_ttl - 1. | Nothing. The cap is reported when it applies; the protocol will not accept a longer horizon in one operation. |
| Exit 2, partial or unconfirmed | The submission’s outcome is not established. | Do not resend. There is no replacement send after an uncertain result — check the chain for the transaction before doing anything else. |
| REFUSED BY WRITE GUARD | The subject is protected. This is the guard working. | Nothing. The refusal is recorded and the run continues. Guards |
In CI
| Symptom | What it means | Do |
|---|---|---|
| Unable to locate executable file: pnpm | Not this Action. setup-node’s package-manager cache detected your lockfile and shelled out to a package manager the runner does not have. | It is disabled inside this Action. If you see it, the failing step is a different one in your workflow. |
| The job passes but the contract is unhealthy | The workflow is probably only failing on exit 1 and treating exit 3 as a pass. | Fail on any non-zero code. An incomplete scan is not a healthy one. Exit codes |
If it is not here
This table lists conditions we have actually produced. Rather than guess, open an issue with the command, the exit code and the output — and note that diagnostics never echo file contents or credentials, so the output is safe to paste.
Next