Error taxonomy and handling patterns
Guides & tutorials3 min read
Locate the failing boundary before you retry or change configuration.
Nexis surfaces failures at a named boundary (auth, connector, wallet, deploy) rather than as an undifferentiated error code. Diagnose which boundary failed before you change configuration or retry blindly.
Symptom-to-boundary map
| Symptom | Boundary | What to check |
|---|---|---|
| Port is busy | Local service startup | Identify the listener before killing it; an expected local service may already be healthy |
| Run has no output | Run execution | Inspect the run event stream, runtime dispatch response, and persisted status separately |
| 401 or 403 | Authentication | Check actor context, session expiry, API-key scopes, org/project binding, and step-up requirements |
| Connector unavailable | Tool gateway | Check connection ownership, required scopes, Token Vault exchange, and gateway source health |
| Wallet action blocked | On-chain engine | Read the capability response, simulation, policy decision, approval expiry, and kill-switch state |
| Deploy looks stale | Deployment | Compare deployed source revision before debugging application behavior |
Auth failures need actor context, not retries
- 401 means the caller isn't authenticated at all; 403 means it is, but lacks the scope, org/project binding, or step-up proof the action requires. Check which one you actually got before assuming a blanket auth failure.
- Financial and irreversible actions may require a fresh step-up token in X-Step-Up-Token; a missing or stale one produces the same 403 shape as a missing scope.
- An approval resolution is validated server-side against the decision, expiry, actor, and step-up proof. A rejected resolve is a signal to re-fetch the current approval state, not to resubmit the same call.
Diagnose before you reconfigure
$ node scripts/setup-agent-local-env.mjs --strict$ pnpm dev:ai:local:check$ pnpm readiness:env:auditFor run and connector failures specifically, cross-reference the run's event stream against its persisted status and the runtime dispatch response. They can disagree during a partial failure. The run ledger stays canonical for status, approvals, artifacts, and receipts; OpenTelemetry spans and Sentry are the fastest way to correlate a failure across the API, tool, sandbox, and on-chain boundaries it crossed.
Do not paper over the boundary
A build, push, or dashboard badge is not proof a deploy landed, and a retried call is not proof an approval was safe to resubmit. Confirm the actual boundary (deployed source, event ledger, approval state) before changing configuration or trying again.
Was this page helpful?
Edit on GitHub