Error codes
The error codes you and your agent meet on manh.run, from the app’s API responses, check rule ids and deploy errors, with what each means and how to fix it.
The page is split by where an error shows up: an API response, a check result, a deploy result. Every code here is a real code in manh.run’s code, so the frontend can branch on it.
Shape of an API error
Every 4xx error from an app’s API has the same JSON shape:
{ "error": "Order not found", "message": "Order not found", "code": "NOT_FOUND" }messageis the sentence a user reads.errorrepeatsmessageso older code keeps working.codeis a fixed id for the frontend to branch on. Errors without a code leave the field out.- An unexpected throw in a handler answers 500 with
{ "error": "INTERNAL", "message": "Máy chủ gặp lỗi, vui lòng thử lại sau.", "code": "INTERNAL" }. The original error goes to the app’s logs, never to the user. - A 5xx you return on purpose with a code, such as
fail(503, "Hệ thống đang bảo trì, quay lại sau 10 phút", "MAINTENANCE"), reaches the user as is, with that status.
In app code, stop a request with fail and your own code:
import { fail } from "manh/errors";
if (!product) fail(404, "Product not found", "NOT_FOUND");
if (product.stock < qty) fail(409, `Only ${product.stock} left`, "OUT_OF_STOCK");Errors from the framework
These arrive before your handler runs, or from a framework helper.
| Status | code | When | What to do |
|---|---|---|---|
| 400 | validation | The body or query does not match the handler’s schema. The response adds fields (field name → message) and issues. The handler does not run. | Show fields next to the matching inputs. If the data is right and it still fails, fix the schema. |
| 401 | UNAUTHENTICATED | A handler that needs a signed-in user was called without a session, after the session expired (7 days) or after the account was locked. | Send the user to the sign-in page. For a handler anyone may call, set export const access = "public". |
| 403 | FORBIDDEN | The user’s role is not in access, or the role may not take that status step. | Check the handler’s access and the roles in app/auth.ts. |
| 409 | FLOW_ILLEGAL | A status change that the declared flow does not have, such as “Cancelled” to “Delivered”. | Show buttons only for the steps allowed from the current status. |
| 429 | RATE_LIMITED | A public write handler (POST, PUT, PATCH, DELETE) got more than 30 calls in 10 minutes from one IP. Carries retry-after. | Change it with export const rateLimit = { max, windowSec }; turn it off with export const rateLimit = false for webhooks from another system. |
| 502 | UPSTREAM_NOT_CONFIGURED, UPSTREAM_UNREACHABLE | The app stands in front of an existing system through app/upstream.ts: the path is not declared, or that system does not answer. | See app/upstream.ts. |
Sign-in errors
These come from the sign-in that manh.run generates from app/auth.ts.
| Status | code | Meaning |
|---|---|---|
| 401 | INVALID_CREDENTIALS | Wrong e-mail or password. Both cases get the same message, so it never tells which e-mails have an account. |
| 401 | ACCOUNT_LOCKED | An account that signs in with Google was locked by an admin. |
| 403 | SIGNUP_CLOSED | The app does not allow sign-up. An admin creates accounts on the users page. |
| 409 | EMAIL_TAKEN | The e-mail is already registered. |
| 409 | SELF_CHANGE | An admin tried to change their own role or lock their own account. |
| 400 | SSO_PROVIDER_OFF | The app has not turned that provider on in providers. |
| 429 | TOO_MANY_ATTEMPTS | 5 wrong passwords for one e-mail, or 30 from one IP, within 15 minutes. Carries retry-after. |
Runtime errors
manh.run returns these when an app is overloaded or reaches a plan limit. The whole group shares one body shape:
{ "code": "APP_BUSY", "error": "APP_BUSY", "message": "Ứng dụng đang bận, thử lại sau giây lát", "retryable": true, "retryAfterSeconds": 1, "requestId": "3f9a2c1b-7d4" }codeis the error code.errorcarries the same value, kept for older code that reads that field.retryablesays whether asking again a moment later can succeed. A used-up monthly quota isfalse.retryAfterSecondsequals theRetry-Afterheader, in seconds.requestIdequals theX-Request-IDheader. Every API response has that header, and a handler reads it withc.req.header("x-request-id"). Quote it when you report a problem to manh.run.
429 means a limit was reached, 503 means busy, 504 means a service behind the app answered too slowly.
useApiClient() and useApi() retry on their own when the answer has retryable: true: they wait exactly Retry-After, or back off with jitter when it is missing, up to 3 attempts and never longer than 8 seconds. Reads (GET) are always retried. Writes (POST, PUT, PATCH, DELETE) are retried only with an idempotency key: api.orders.create(body, { idempotencyKey }), see useApiClient. The last error still reaches the page, with error.ftCode and error.requestId.
| Status | error | Meaning | What to do |
|---|---|---|---|
| 429 | RATE_LIMITED | The app got more requests per minute than its plan allows. retry-after points to the end of the minute. | Cut repeated calls (batch requests, poll less often). Per-plan numbers are in Plan limits. |
| 503 | CPU_LIMIT | One route used more CPU per request than the plan allows 3 times within a minute, so it is paused for 60 seconds. Other routes keep working. The app owner gets one e-mail. | Find the heavy loop or query in that route. Move long work to a background job. |
| 503 | APP_BUSY | The app is overloaded. retry-after: 1. | The client retries on its own. If it keeps happening, look for slow requests in the logs. |
| 503 | EGRESS_BUSY | An outgoing call of the app (fetch to another service) could not leave because the way out is busy. The handler gets this 503 response instead of a thrown error. | Return an error to the user, or move the work to a background job that runs again later. |
| 503 | APP_ERROR | The app does not answer, usually because it fails while starting. | Open the logs, fix the error and deploy again. |
| 503 | APP_SUSPENDED | The app is paused, for example because the project is in the trash. | Restore the project, then deploy again. |
| 429 | TOO_MANY_CONNECTIONS | More live-update connections are open than the plan allows. | Close connections on pages that are no longer open. |
Using up a monthly limit (requests, database size) does not stop the app. manh.run e-mails the owner at 80% and 100%.
Errors from the built-in services
manh/email and manh/openai throw errors with the status and code below. Wrap calls in try/catch so the main work of the request does not fail with them.
| Status | Code | Meaning |
|---|---|---|
| 429 | BUILTIN_QUOTA_EXCEEDED | The plan’s e-mails (per day or month) or AI tokens (per month) are used up. Shared by every app of the account. The app keeps running. |
| 400 | EMAIL_TOO_MANY_RECIPIENTS | One e-mail has more than 10 recipients (to + cc + bcc). Send one message per recipient. |
| 400 | BUILTIN_MODEL_NOT_ALLOWED | Unknown AI model name. Use gpt-4o-mini, gpt-4o or text-embedding-3-small. |
| 413 | BUILTIN_TOO_LARGE | The AI request body is over 256 KB. Send only the text the task needs. |
| 501 | BUILTIN_UNSUPPORTED | An AI feature that does not exist: images, audio, files. Only chat and embeddings are available. |
| 424 | SUPABASE_NOT_CONNECTED | The app called Supabase before the owner connected it. See Supabase. |
Check rule ids
check reports each error with a rule id, file and line. The table lists the ids agents meet most. The full list by group is in Check rules; how to read one error line is in Reading check errors.
| Id | Meaning | Fix |
|---|---|---|
code.syntax-error | The file does not parse. | Rewrite the file and count opening and closing brackets. Fix this first: it pauses most other rules. |
code.undefined-component | <Name /> is used without an import or declaration. | Add the import. Left as is, the page crashes with ”… is not defined”. |
ui.unknown-icon | The icon name is not in @ant-design/icons. | Use a real name (Outlined, Filled, TwoTone suffix); the message suggests the closest ones. |
code.antd-v6-no-visible-prop | visible on an antd v6 Modal, Drawer… | Use open. |
code.invalid-api-method | api.<resource>.<fn>() is not in the generated client. | Use a function from the list in the message, or add the handler. |
code.api-namespace-called-as-function | api.orders(...) called as a function. | Call a member, for example api.orders.create(body). |
code.frontend-subpath-unavailable | A .tsx file imports a package subpath the app does not serve. | Import from the package name itself. |
code.no-app-api-folder | A file under app/api/. | Move it to app/<resource>/<method>.ts. |
code.no-framework-file-emit | A hand-written app/db.ts, app/api.ts or app/hooks.ts. | Delete it. Tables go in <resource>.table.ts. |
DUPLICATE_PAGE, DUPLICATE_HANDLER, DUPLICATE_CRON | Two files map to the same URL, the same method and path, or the same cron job name. | Merge or rename one of them. |
code.runtime-import | A runtime import other than import { env } from "manh/env". | Read secrets through env.NAME. |
code.backend-package-not-allowed, code.package-denied | A package that is not on the server list, or is denied. | Use a package the message lists; see Versions. |
code.backend-import-unresolved | An import in a .ts file points at nothing, or only at a .tsx file. | Fix the path. Code shared by both sides goes in app/shared. |
code.no-remote-import, code.no-npm-specifier | An import by URL or npm:…@version. | Import by package name, without a version. |
code.unknown-std-import | An manh/<name> that does not exist. | Use a module that exists in app/std. |
code.no-async-transaction | db.transaction(async …). | Run every check first, then write. |
code.no-dayjs-in-backend | dayjs in a .ts file. | Use Date, or manh/vn for Vietnam time. |
code.hardcoded-secret, code.no-reserved-env | An API key written in code, or a reserved name such as OPENAI_API_KEY. | Put the secret in the dashboard. Built-in services need no key. |
code.jwt-verify-alg | verify(token, secret) without "HS256". | Pass "HS256" as the third argument. |
auth.config-invalid, access.unknown-role | app/auth.ts has the wrong shape, or access names a role missing from roles. | Follow the message; roles must be literal values. |
code.cron-missing-schedule, code.cron-invalid-schedule | A .cron.ts file without schedule, or a schedule without exactly 5 fields. | Add export const schedule = "0 1 * * *" (UTC). |
Deploy errors
Your agent gets these as one line of text that starts with the code.
| Code | Meaning | What to do |
|---|---|---|
CHECK_FAILED | check still has errors, so the deploy is refused. The error list comes with it. | Fix them and deploy again. If only type or render errors remain and you are sure the app works, the agent calls deploy({ force: true, reason }). |
FORCE_NEEDS_REASON | force: true without a reason of at least 5 characters. | Say why those errors do not affect the app. |
PLAN_LIMIT | The app has more cron jobs than the plan allows, or the account has more projects than the plan allows. Then only the most recently deployed projects can deploy again. | Merge jobs that share a schedule into one file, or delete projects. The running app stays as it is. |
CRON_TOO_MANY_SCHEDULES | More than 20 distinct cron schedules in one app. | Merge jobs that share a schedule. |
CHECKPOINT_LIMIT | The project already has 100 named checkpoints. | Delete old ones in the Deploys & history tab. |
TOOL_FAILED | An unexpected error. Nothing changed unless the message says so. | Retry once. If it repeats, look at the project state and the logs. |
A file tree that deployed once can always deploy again, even if check now reports errors. That way a rollback is never blocked.
The agent’s database commands add a few codes. ENV_NOT_PROVISIONED: the project has not deployed, so it has no database yet. READ_ONLY: a write sent through the read-only command. NOT_A_WRITE: a read sent through the write command. INTERNAL_TABLE: a write to one of manh.run’s system tables.
The testing commands add: NO_TESTS (no spec/acceptance.json yet), BAD_TESTS (the file is malformed, with where), NOT_DEPLOYED (tests need a deployed app), NO_SIGN_IN (a step uses as but the app has no app/auth.ts) and UNKNOWN_ROLE (a role not in app/auth.ts). The image command returns NO_IMAGE when it gets neither a link nor a file.
A deploy never drops a column or a table, and never changes a column’s type. Its notes flag two cases to read carefully: a new .notNull() column without .default() is added as nullable, and a unique index cannot be built because existing rows are duplicated. The database has no backup, so read the notes before you fix data by hand.
Next steps
- Check rules: every rule by group.
- Plan limits: requests, CPU, e-mail and AI per plan.
- Troubleshooting: common symptoms and fixes.