Browse documentation
Troubleshooting
Diagnose failures by locating the last successful phase in the run lifecycle.
View MarkdownStart with the run Details, then use Activity and Diagnostics to locate the phase that failed.
Admission
| Symptom | Check |
|---|---|
401 authentication_error | Bearer header, key value, key mode, revocation and environment |
403 permission_error | Required API-key scope |
| Model not found | Active agent slug and workspace ownership |
| Billing readiness failure | Billing-owner workspace and payment state |
List active model identifiers:
curl "$SALAMBO_BASE_URL/api/v1/models" \
-H "Authorization: Bearer $SALAMBO_API_KEY"Deployment
| Symptom | Check |
|---|---|
| Manifest rejected | salambo manifest --path . --json diagnostics |
| Source upload failed | API authority, archive size and network |
| Managed build rejected | Unsupported image or project configuration |
| Missing secret variable | Export the fromEnv variable before deploy |
| Deployment never becomes ready | Deployment status and build Diagnostics |
Sandbox
| Symptom | Check |
|---|---|
| Sandbox cannot start | Deployment readiness, region and machine availability |
| Runtime contract error | Managed image health and runtime update guidance |
| Tool command denied | Requested path and workspace permissions |
| External request denied | Egress policy and host-only allowlist |
Provider
| Symptom | Check |
|---|---|
| Authentication failure | Provider secret and exposure target |
| Provider unavailable | Provider status and bounded retry |
| Model rejected | Provider name, model identifier and account access |
| Missing provider key in sandbox | The secret may be runtime-only by design |
Extensions and tools
| Symptom | Check |
|---|---|
| Extension missing | .pi/extensions/, package resources, and manifest diagnostics |
hosted_pi_version_incompatible | Pi peer range must include the documented 0.83 profile |
hosted_pi_capability_local_only | Move interactive commands, UI, or editor behavior to a local Pi extension |
hosted_pi_capability_unsupported | Remove session-tree or entry-label behavior from the hosted entrypoint |
hosted_pi_native_module_unsupported | Replace the native add-on with a portable JavaScript or external-service alternative |
| Tool inactive | Extension registration and the latest setActiveTools() selection |
| Extension startup failed | Compiled entrypoint, package-relative dependencies, and runtime diagnostics |
| Tool timed out | Extension deadline, cancellation signal, sandbox command, and external dependency |
Workspace and checkpoints
| Symptom | Check |
|---|---|
| Turn failed after output | Post-turn checkpoint may have failed |
| Follow-up cannot resume | Latest ready checkpoint and sandbox recreation |
| Upgrade failed | Checkpoint, provisioning, restore or runtime validation phase |
| New seed file missing | Seeds apply only to new runs, not existing durable workspaces |
Cancellation and cleanup
A completed turn followed by a cancelled or stopped sandbox can represent successful work followed by intentional cleanup.
Check turn outcomes before treating the final run state as a failure.
Stale browser after deployment
If a save action fails immediately after a web deployment, hard refresh the page. A page loaded from the previous application bundle can submit an outdated server-action identifier.