Reading check errors
Each check error line has a layer, a rule id, a file and a line; this page explains the common ones and how to get an agent out of a fix loop.
Most of the time the agent reads and fixes errors on its own. You read the result when a deploy is refused, or when the agent is fixing the same error for the third time.
Anatomy of a line
- [gate:code.invalid-api-method] app/orders/page.tsx:31 api.orders.stats() is not in the generated client …
│ │ │ │ └ message, always with the fix
│ │ │ └ line
│ │ └ file
│ └ rule id
└ layer: syntax · gate · contract · typesErrorsblock deploy.Warningsdon’t, but point at places where the app will be slow, look off or be hard to maintain.- Look up rule ids in check rules.
Common errors
syntax: a missing bracket, unclosed JSX. Fix these first; most other rules pause while syntax errors remain.code.invalid-api-method: the page callsapi.<resource>.<fn>()that the client doesn’t have. The message lists the valid names. Call a valid one, or write the missing handler.contract“FE calls … but no matching BE route”: the page calls a path with no handler. Add the handler file at that path.code.antd-v6-no-visible-prop:visibleon an antd v6ModalorDraweris ignored, so it never opens. Useopen.code.no-css-import,code.no-tailwind-import,code.no-mui: the agent reached outside the stack. Ask it to use antd and Tailwind classes inclassName.code.backend-package-not-allowed: a server package that isn’t on the allowlist. The message lists the allowed ones; oftenmanh/*already does the job.access.unknown-role:accessnames a role thatapp/auth.tsdoesn’t have. Fix the name or add the role toroles.code.no-async-transaction:db.transaction(async …). Check everything before writing, or use a synchronous callback.types: TypeScript errors fromcheck({ typecheck: true })or a deploy. Usually a handler returns a different shape from what the page uses, or an import is missing.
When the agent goes in circles
Signs: the same rule id comes back after two or three writes, or each fix creates a new error in the same spot.
- Paste the exact error line to the agent and say what you want in words: “This page needs order totals per month. Write the handler
app/orders/stats/get.ts; don’t call anything else.” - Ask the agent to reread the relevant docs through
framework_docsbefore fixing again. - If the problem is something the agent started wrong (a library outside the stack, a different file layout), ask it to go back to the last checkpoint and redo that part.
A refused deploy
Deploy runs all four layers. With errors left, manh.run refuses, returns the list, and the running app stays as it was.
- Errors in the first three layers can’t be skipped. Fix them.
- Only type errors can be skipped, with
deploy({ force: true, reason }). Agree only after you tried the app in the preview and it works; put the real reason inreason. - A file tree that once deployed successfully can always deploy again, even after new rules.
Tests fail after a deploy
After a deploy, manh.run runs the app’s tests on a copy with its own database and returns the results in tests. The tests come from spec/acceptance.json; until the app has that file, manh.run generates a few basic ones: each role opens the home page, the other screens open, every list answers 200 or 403, never 500.
A failing test means the app doesn’t yet do what the business needs. Ask the agent to fix the app and deploy again, not to change the test until it passes.
Good to know
- The
code.missing-frontendwarning is normal while the data and API are being built. hint.*warnings point at a built-in feature that the code is rewriting by hand (error messages, Vietnam time, Excel export). Ask the agent to use the built-in.
Next steps
- Check and fix errors — the four check layers and when they run.
- check rules — look up one rule id, by group.
- Rollback and checkpoints — go back when a change heads the wrong way.