Deploy and monitor
Troubleshooting
Diagnose setup, streaming, tool, and deployment problems by their symptoms.
| Symptom | Check | Next action |
|---|---|---|
| SDK installation fails | The starter uses a repository workspace package | Follow TypeScript setup, or use HTTP |
| Client construction fails before a request | CEREAL_API_KEY is missing; the SDK does not load the CLI login | Pass the credential in the server process |
| Setup works but starting a session is forbidden | control does not imply data or read | Check the operation's required scopes in credentials |
An API key reports environment_mismatch | A header conflicts with the key’s environment | Remove the selector or use the intended environment’s key |
| Agent cannot call a local tool | The application development channel stopped | Restart cereal dev or the starter; inspect connection status |
| Production callbacks return 401 | Origin, path, body bytes, or expected tenancy differ | Check verification and the mounted endpoint |
| Token minting fails with a read-only key | sessions.streamToken requires data | Mint on an authorized application server with the correct scope |
| Browser stream returns 401 | Token expired or was not renewed | Use a token-source function in subscribe |
| Browser stream returns 400 | Requested format differs from the token's pinned format | Use the same format in issuance and subscription |
| Chat is empty after reload | A cursor was saved without the transcript | Replay from the beginning or persist both state and cursor |
| Session is idle but there is no final answer | The stop reason is not completed | Inspect stopReason, pending approvals, and trace |
| Approval returns a conflict | Another action answered, expired, or superseded it | Refresh pending decisions; do not retry indefinitely |
| An SDK method is undefined | The HTTP operation may not have a wrapper | Check TypeScript signatures and coverage |
| Copy to environment cannot resolve dependencies | The target is missing named resources | Configure target resources or change the reference mappings, then check again |
For support, include the environment, session ID, operation name, error tag, and request or trace ID when available. Keep API keys, model keys, and stream tokens out of reports.