# Troubleshooting

Diagnose failures by locating the last successful phase in the run lifecycle.

Start 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:

```bash
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.