Error Reference
Deploy errors
| Code |
Meaning |
Fix |
| MISSING_MAIN |
main.ts not in files |
Add main.ts with export default handler |
| DEPLOY_ERROR |
Provider rejected deploy |
Check project_id exists; retry |
| NO_FILES |
deploy() called with no staged files |
Pass files directly or call stage_files first |
Runtime errors (visible in check_app / get_app_logs)
| Symptom |
Cause |
Fix |
| status: 0, "context deadline exceeded" |
Deno.serve() in main.ts or startup crash |
Change to export default handler |
| status: 0 after correct pattern |
Machine stopped after crash |
Check get_app_logs for the actual error |
| status: 500 |
Unhandled exception in handler |
Fix the error shown in get_app_logs |
| DB connection timeout |
ssl: true or bad URL parsing |
Use the pgConfig() pattern from docs/database |
Project errors
| Code |
Meaning |
Fix |
| NAME_TAKEN |
Project name already used globally |
Choose a different name |
| RESERVED_NAME |
Name is reserved (admin, api, www…) |
Choose a different name |
| PROJECT_NOT_FOUND |
project_id does not exist |
Call create_project first |
| PROJECT_LOCKED |
The owner locked this app; mutations are blocked |
Do NOT retry. See "Locked apps" below |
Locked apps
The owner can lock an app from the web dashboard. While locked, every mutating tool returns
PROJECT_LOCKED and refuses the change: deploy, edit_file, stage_files, execute_sql,
apply_migrations, rollback_to_version, upload_asset, delete_version, delete_project, and
apply_changes (onto the locked main app).
PROJECT_LOCKED is not retryable — re-running the tool will fail again. There is intentionally
no tool to unlock: only the human owner can unlock, and only from the dashboard. When you hit
it:
- Tell the user the app is locked and that they must unlock it from the dashboard (the error's
Hint contains the URL). Do not loop or retry.
- If they want to keep working without unlocking, offer a draft:
create_draft works even on
a locked app, so you can iterate in the private copy. Applying it back
(apply_changes) still requires the main app to be unlocked first.
These operations are always allowed on a locked app: all reads (check_app,
read_project_files, query_sql, get_app_logs, get_exceptions, list_versions…),
create_version, fork_project, and create_draft.
Validation errors
| Code |
Meaning |
Fix |
| VALIDATOR_UNAVAILABLE |
Deno not available on server |
Skip validation, deploy directly |
| VALIDATOR_TIMEOUT |
Validation took >60s (large deps) |
Retry; deps are now cached |
Logs errors
| Code |
Meaning |
Fix |
| LOGS_ERROR |
Cannot fetch logs |
Wait a few seconds and retry; machine may be starting |