Troubleshooting
Common problems when building apps on manh.run, from a blank preview, import errors and 401 after deploy to cron jobs that never run and e-mail that never arrives, with causes and fixes.
Each entry gives the symptom, the cause and the fix. Most fixes are one sentence you pass to your agent. Error codes mentioned here are explained in Error codes.
Frontend
The preview is blank
Cause. Usually one of three things:
- A hand-written
layout.tsxframe forgets to render<Outlet />, so child pages never show. A layout built onAppShellfrommanh/shellalready has it. - A page uses a component it never imported and crashes with ”… is not defined”.
- A page calls an API that returns an error, then reads
undefineddata.
Fix. Ask your agent to run check({ typecheck: true }) and fix every error. Type errors and missing imports show up there. If check is clean and the page is still blank, open the browser console and send the first red error line to your agent.
import { Outlet } from "react-router";
export default function Layout() {
return (
<main>
<Outlet />
</main>
);
}A change shows in the preview but not on the live app
Cause. When the agent writes files, only the preview changes. The app at <id>.manh.run runs the last deploy.
Fix. Ask your agent to deploy. The project’s Deploys & history page shows the last deploy and the files it changed. See Deploy.
A dialog never opens, or an icon shows ”?”
Cause. Two old or wrong patterns agents often write. antd v6 ignores visible on Modal and Drawer. An icon name that is not in @ant-design/icons shows as ”?”.
Fix. Use open={…}. Use a real icon name such as PlusOutlined. check reports both: code.antd-v6-no-visible-prop and ui.unknown-icon.
A form does not submit, or rejects a date
Cause. Two common ProForm mistakes. One: submitter.render picks buttons by position in dom after one of them was turned off, so the submit button disappears. Two: a date field with fieldProps.format sends the display string, such as 20/11/2026, and the API answers 400 validation.
Fix. Drop submitter.render, or render the submit button explicitly. For the date field, convert the value with transform before it is sent. check warns on the second case with code.proform-date-format-submit.
A list page gets slower as data grows
Cause. The list sorts or filters on a column without an index, reads the whole table each time, or runs one query per row.
Fix.
- Add an index on the columns used to sort and filter.
checkwarns withperf.order-unindexed. - Page with listOf, at most 100 rows per page. A hand-written
pageSizewithout.max(…)triggerslist.unbounded. - Load related rows with one
inArrayquery instead of a query inside a loop. - Count rows with
count(), notrows.length.
Imports and check
check fails on an import line
Cause. The file imports something the app does not have:
- A server package that is not on the list:
code.backend-package-not-allowed. - A path to a missing file, or a
.tsfile importing a.tsxfile:code.backend-import-unresolved. - A frontend package subpath the app does not serve:
code.frontend-subpath-unavailable. - An import by URL or
npm:…@version:code.no-remote-import,code.no-npm-specifier.
Fix. Read the error line: it lists the valid packages or paths. Code needed on both the frontend and the server goes in app/shared. The package list is in Versions.
The agent keeps fixing the same check error
Cause. A leftover syntax error pauses most other rules, or the agent fixes the symptom without reading the whole message.
Fix. Ask the agent to fix code.syntax-error first, then run check again. How to get an agent out of a fix loop: Reading check errors.
Sign-in and access
The API returns 401 after deploy
Cause. Once an app has app/auth.ts, every handler needs a signed-in user by default. A public page (home page, contact form) calling such a handler gets 401 UNAUTHENTICATED. Sessions also expire after 7 days.
Fix. Set export const access = "public" on handlers that visitors call before signing in. For an expired session, the frontend sends the user back to sign-in.
import { z } from "zod";
import { saveContact } from "./repository";
export const access = "public";
export const schema = { body: z.object({ name: z.string().min(1), phone: z.string() }) };
export default (c, { body }) => saveContact(body);The first account has no admin rights
Cause. The admin role (the first role in roles) goes only to the first account registered from the owner’s workspace preview. Accounts registered on the live app get the default role.
Fix. Open the preview in the workspace and register the admin account there. The admin then changes other users’ roles on the users page. To try each role before handing the app over, ask the agent for one test account per role (create_test_accounts); never promote an account with SQL. See app/auth.ts.
Sign-in returns 429 TOO_MANY_ATTEMPTS
Cause. The app’s built-in sign-in locks for a while after 5 wrong passwords for one e-mail, or 30 wrong tries from one IP, within 15 minutes. This stops password guessing.
Fix. Wait for the time in Retry-After, then sign in with the right password. A correct sign-in resets the counters. The UI should show the server’s message, not retry on its own.
A public form returns 429 RATE_LIMITED
Cause. A public write handler accepts 30 calls per 10 minutes from one IP. People on the same office network share one IP.
Fix. Raise the limit for that handler, or turn it off for webhooks from another system:
export const access = "public";
export const rateLimit = { max: 200, windowSec: 600 };Data
Data seems gone after renaming a column
Cause. Deploys only add; they never drop or rename. Renaming a column in .table.ts creates a new, empty column. The old data is still in the old column, but the code no longer reads it.
Fix. Put the old name back in the code and the data shows again. To rename for real: add the new column, copy the data with one UPDATE, switch the code to the new column, and drop the old one last.
manh.run keeps no backup of the database. A code rollback does not bring data back. Before any UPDATE or DELETE, run the same WHERE as SELECT COUNT(*) to see how many rows will change. Before a big change, export the table to CSV from the project’s Database page.
Deleting a record fails with FOREIGN KEY constraint failed
Cause. Foreign keys are enforced. Deleting a customer who still has orders, or adding an order for a missing customer, is refused by the database.
Fix. Pick onDelete on purpose in .references(…): "cascade", "set null" or "restrict". In the repository, check for child rows first and return a 409 with a clear message, such as “This customer still has orders”.
Sample data shows up twice
Cause. The code that creates sample data ran more than once, adding a new set each time.
Fix. Count rows before inserting and insert only into an empty table. Delete test data by the ids of the rows you created, never with a broad condition.
Times are 7 hours off
Cause. The server stores and computes times in UTC. Vietnam is UTC+7.
Fix. Format dates and times for people with manh/vn. Cron schedules are UTC too: 8 a.m. in Vietnam is 0 1 * * *.
Cron, e-mail, Telegram
A cron job never runs
Cause. Most often:
- The schedule is written in local time while cron runs in UTC.
- The file is not named
*.cron.ts, or has noexport const schedule. - The app is not deployed. Cron jobs run on the deployed app only, never in the preview.
- The run throws. manh.run retries up to 3 times, then logs the error.
Fix. Check the schedule and the file name, deploy, then read the logs. Write the job so that a re-run does not corrupt data. See *.cron.ts.
E-mail never arrives
Cause.
- The recipient is a sample address (
example.com,.test,.invalid,.example). manh.run does not send it,email()returns{ ok: false, skipped: true }and the logs show[email] FAILED … demo address. - The daily or monthly e-mail limit is used up:
BUILTIN_QUOTA_EXCEEDED. - The code calls
email()before writing to the database, and the request fails halfway. - The message landed in the recipient’s spam folder.
Fix. Open the logs: every send leaves an [email] sent or [email] FAILED line with the reason. Check ok in the result before telling the user it was sent. Call email() after the write, inside try/catch. See Send and receive email.
The Telegram bot is silent
Cause.
- The owner has not connected a bot in the project’s Connections › Telegram.
sendandlinkUrlthrow “Telegram is not connected”. - The recipient never pressed Start through their own link, so the app has no
chatIdfor them. - The function in
*.telegram.tsthrows. The error goes to the logs and Telegram does not resend, so the user gets nothing. - The recipient blocked the bot. The send error has
err.blocked === true.
Fix. Connect the bot, then ask users to press the notifications button in the app. Catch errors in the function and return a plain sentence. See *.telegram.ts.
AI cannot read an image or a scanned PDF
Cause. manh/openai has text models only. Images, audio and files are not available: BUILTIN_UNSUPPORTED.
Fix. Send text only. For paper documents, let users type the key fields, then use AI to check or summarize the text.
Next steps
- Logs — server errors, cron runs and e-mails the app sent.
- Rollback and checkpoints — put the app back on its last good build, then keep fixing.
- Error codes — look up one error code and how to handle it.