Skip to Content

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 · types
  • Errors block deploy. Warnings don’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 calls api.<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: visible on an antd v6 Modal or Drawer is ignored, so it never opens. Use open.
  • 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 in className.
  • code.backend-package-not-allowed: a server package that isn’t on the allowlist. The message lists the allowed ones; often manh/* already does the job.
  • access.unknown-role: access names a role that app/auth.ts doesn’t have. Fix the name or add the role to roles.
  • code.no-async-transaction: db.transaction(async …). Check everything before writing, or use a synchronous callback.
  • types: TypeScript errors from check({ 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.

  1. 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.”
  2. Ask the agent to reread the relevant docs through framework_docs before fixing again.
  3. 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 in reason.
  • 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-frontend warning 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

Last updated