Reference

Errors

Error response format and common status codes.

For agents: Parse error.code and error.message, report both, and use events for owner-visible runtime detail.

Shape

{
  "error": {
    "code": "invalid_path",
    "message": "Release path must be relative."
  }
}

Common statuses are 400, 401, 403, 404, 409, 413, and 429.

Common Codes

invalid_path: a release file path is absolute, contains .., or targets _userland/.
missing_static_root: runtime.static_root does not match any published file.
missing_server_entry: runtime.server_entry does not match a published server file.
invalid_resource_manifest: resource declarations failed validation.
pending_secrets: activation is blocked until required app secrets are set.
requires_migration: durable resource changes need an explicit migration plan.

Recovery

Use the CLI to inspect and recover:

npm run userland -- apps events "$APP_ID" --limit 25
npm run userland -- apps releases "$APP_ID"
npm run userland -- apps rollback "$APP_ID" "$RELEASE_ID"

See /guides/troubleshooting for the full debug path.