Skip to Content

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" }
  • message is the sentence a user reads. error repeats message so older code keeps working.
  • code is 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:

app/orders/repository.ts
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.

StatuscodeWhenWhat to do
400validationThe 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.
401UNAUTHENTICATEDA 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".
403FORBIDDENThe 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.
409FLOW_ILLEGALA 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.
429RATE_LIMITEDA 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.
502UPSTREAM_NOT_CONFIGURED, UPSTREAM_UNREACHABLEThe 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.

StatuscodeMeaning
401INVALID_CREDENTIALSWrong e-mail or password. Both cases get the same message, so it never tells which e-mails have an account.
401ACCOUNT_LOCKEDAn account that signs in with Google was locked by an admin.
403SIGNUP_CLOSEDThe app does not allow sign-up. An admin creates accounts on the users page.
409EMAIL_TAKENThe e-mail is already registered.
409SELF_CHANGEAn admin tried to change their own role or lock their own account.
400SSO_PROVIDER_OFFThe app has not turned that provider on in providers.
429TOO_MANY_ATTEMPTS5 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" }
  • code is the error code. error carries the same value, kept for older code that reads that field.
  • retryable says whether asking again a moment later can succeed. A used-up monthly quota is false.
  • retryAfterSeconds equals the Retry-After header, in seconds.
  • requestId equals the X-Request-ID header. Every API response has that header, and a handler reads it with c.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.

StatuserrorMeaningWhat to do
429RATE_LIMITEDThe 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.
503CPU_LIMITOne 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.
503APP_BUSYThe app is overloaded. retry-after: 1.The client retries on its own. If it keeps happening, look for slow requests in the logs.
503EGRESS_BUSYAn 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.
503APP_ERRORThe app does not answer, usually because it fails while starting.Open the logs, fix the error and deploy again.
503APP_SUSPENDEDThe app is paused, for example because the project is in the trash.Restore the project, then deploy again.
429TOO_MANY_CONNECTIONSMore 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.

StatusCodeMeaning
429BUILTIN_QUOTA_EXCEEDEDThe 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.
400EMAIL_TOO_MANY_RECIPIENTSOne e-mail has more than 10 recipients (to + cc + bcc). Send one message per recipient.
400BUILTIN_MODEL_NOT_ALLOWEDUnknown AI model name. Use gpt-4o-mini, gpt-4o or text-embedding-3-small.
413BUILTIN_TOO_LARGEThe AI request body is over 256 KB. Send only the text the task needs.
501BUILTIN_UNSUPPORTEDAn AI feature that does not exist: images, audio, files. Only chat and embeddings are available.
424SUPABASE_NOT_CONNECTEDThe 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.

IdMeaningFix
code.syntax-errorThe 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-iconThe 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-propvisible on an antd v6 Modal, Drawer…Use open.
code.invalid-api-methodapi.<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-functionapi.orders(...) called as a function.Call a member, for example api.orders.create(body).
code.frontend-subpath-unavailableA .tsx file imports a package subpath the app does not serve.Import from the package name itself.
code.no-app-api-folderA file under app/api/.Move it to app/<resource>/<method>.ts.
code.no-framework-file-emitA 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_CRONTwo 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-importA runtime import other than import { env } from "manh/env".Read secrets through env.NAME.
code.backend-package-not-allowed, code.package-deniedA package that is not on the server list, or is denied.Use a package the message lists; see Versions.
code.backend-import-unresolvedAn 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-specifierAn import by URL or npm:…@version.Import by package name, without a version.
code.unknown-std-importAn manh/<name> that does not exist.Use a module that exists in app/std.
code.no-async-transactiondb.transaction(async …).Run every check first, then write.
code.no-dayjs-in-backenddayjs in a .ts file.Use Date, or manh/vn for Vietnam time.
code.hardcoded-secret, code.no-reserved-envAn 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-algverify(token, secret) without "HS256".Pass "HS256" as the third argument.
auth.config-invalid, access.unknown-roleapp/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-scheduleA .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.

CodeMeaningWhat to do
CHECK_FAILEDcheck 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_REASONforce: true without a reason of at least 5 characters.Say why those errors do not affect the app.
PLAN_LIMITThe 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_SCHEDULESMore than 20 distinct cron schedules in one app.Merge jobs that share a schedule.
CHECKPOINT_LIMITThe project already has 100 named checkpoints.Delete old ones in the Deploys & history tab.
TOOL_FAILEDAn 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

Last updated