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:

1. 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.
2. 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