Skip to Content

Khắc phục sự cố

Các sự cố hay gặp khi làm app trên manh.run, từ trang trắng, lỗi import, 401 sau deploy đến cron không chạy và email không tới, kèm nguyên nhân và cách sửa.

Mỗi mục có triệu chứng, nguyên nhân và cách sửa. Phần lớn cách sửa là một câu bạn chuyển cho agent. Mã lỗi nhắc tới ở đây được giải thích ở Mã lỗi.

Giao diện

Bản xem trước trắng trơn

Nguyên nhân. Thường gặp ba trường hợp:

  • layout.tsx tự viết khung mà quên render <Outlet />, nên trang con không hiện. Layout dùng AppShell từ manh/shell thì đã có sẵn chỗ này.
  • Trang dùng một component chưa import, và trang hỏng khi chạy với lỗi ”… is not defined”.
  • Trang gọi một API trả lỗi, rồi đọc dữ liệu undefined.

Cách sửa. Bảo agent chạy check({ typecheck: true }) và sửa mọi lỗi. Lỗi kiểu và component thiếu import hiện ra ở bước này. Nếu check sạch mà trang vẫn trắng, mở console của trình duyệt và gửi dòng lỗi đỏ đầu tiên cho agent.

app/layout.tsx
import { Outlet } from "react-router"; export default function Layout() { return ( <main> <Outlet /> </main> ); }

Sửa xong mà app chạy thật không đổi

Nguyên nhân. Agent ghi file chỉ đổi bản xem trước. App ở <id>.manh.run chạy bản của lần deploy gần nhất.

Cách sửa. Bảo agent deploy. Mục Deploy & lịch sử của project cho biết lần deploy cuối và các file đã đổi. Xem Deploy.

Hộp thoại không mở, icon hiện dấu ”?”

Nguyên nhân. Hai cách viết cũ hoặc sai mà agent hay dùng. visible trên Modal và Drawer của antd v6 bị bỏ qua. Tên icon không có trong @ant-design/icons hiện thành dấu ”?”.

Cách sửa. Dùng open={…}. Dùng tên icon có thật, ví dụ PlusOutlined. check báo cả hai: code.antd-v6-no-visible-prop và ui.unknown-icon.

Form bấm Lưu mà không gửi, hoặc báo lỗi ngày

Nguyên nhân. Hai lỗi hay gặp với ProForm. Một là submitter.render lấy nút theo vị trí trong dom sau khi đã tắt một nút, nên nút Gửi biến mất. Hai là ô ngày có fieldProps.format gửi chuỗi hiển thị như 20/11/2026, và API trả 400 validation.

Cách sửa. Bỏ submitter.render, hoặc vẽ nút Gửi tường minh. Với ô ngày, đổi giá trị bằng transform trước khi gửi. check cảnh báo trường hợp thứ hai bằng code.proform-date-format-submit.

Trang danh sách chậm dần khi dữ liệu nhiều lên

Nguyên nhân. Danh sách sắp xếp hoặc lọc theo cột không có index, đọc cả bảng mỗi lần, hoặc gọi một truy vấn cho từng dòng.

Cách sửa.

  • Thêm index cho cột dùng để sắp xếp và lọc. check cảnh báo bằng perf.order-unindexed.
  • Dùng listOf để phân trang, tối đa 100 dòng một trang. pageSize viết tay không có .max(…) bị cảnh báo list.unbounded.
  • Lấy dữ liệu liên quan bằng một truy vấn inArray thay vì truy vấn trong vòng lặp.
  • Tính tổng số dòng bằng count(), không bằng rows.length.

Import và check

check báo lỗi ở dòng import

Nguyên nhân. File import thứ app không có:

  • Package server không có trong danh sách: code.backend-package-not-allowed.
  • Đường dẫn tới file không có, hoặc file .ts import một file .tsx: code.backend-import-unresolved.
  • Đường dẫn con của package giao diện mà app không có: code.frontend-subpath-unavailable.
  • Import bằng URL hoặc npm:…@phiên-bản: code.no-remote-import, code.no-npm-specifier.

Cách sửa. Đọc dòng lỗi: nó liệt kê package hoặc đường dẫn hợp lệ. Hàm cần dùng ở cả giao diện lẫn server đặt trong app/shared. Danh sách package xem ở Phiên bản.

Agent sửa mãi một lỗi check

Nguyên nhân. Lỗi cú pháp còn sót làm phần lớn luật khác tạm dừng, hoặc agent sửa triệu chứng mà chưa đọc hết thông báo.

Cách sửa. Bảo agent sửa code.syntax-error trước, rồi chạy lại check. Cách đưa agent ra khỏi vòng sửa lặp xem ở Đọc lỗi check.

Đăng nhập và quyền

API trả 401 sau khi deploy

Nguyên nhân. Khi app có app/auth.ts, mọi handler mặc định cần đăng nhập. Trang công khai (trang chủ, form liên hệ) gọi handler đó sẽ nhận 401 UNAUTHENTICATED. Phiên đăng nhập cũng hết hạn sau 7 ngày.

Cách sửa. Đặt export const access = "public" cho handler mà khách chưa đăng nhập cần gọi. Với phiên hết hạn, giao diện đưa người dùng về trang đăng nhập.

app/contact/post.ts
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);

Tài khoản đầu tiên không có quyền quản trị

Nguyên nhân. Vai quản trị (vai đầu tiên trong roles) chỉ được gán cho tài khoản đầu tiên đăng ký từ bản xem trước trong không gian làm việc của chủ app. Đăng ký trên app chạy thật nhận vai mặc định.

Cách sửa. Mở bản xem trước trong không gian làm việc và đăng ký tài khoản quản trị ở đó. Sau đó quản trị viên đổi vai cho người khác ở trang người dùng. Muốn thử từng vai trước khi giao app, bảo agent tạo tài khoản thử cho mỗi vai (create_test_accounts), đừng nâng quyền bằng SQL. Xem app/auth.ts.

Đăng nhập báo 429 TOO_MANY_ATTEMPTS

Nguyên nhân. Đăng nhập có sẵn của app khoá tạm sau 5 lần sai mật khẩu với cùng một email, hoặc 30 lần sai từ cùng một IP, trong 15 phút. Đây là cách chặn người dò mật khẩu.

Cách sửa. Chờ hết thời gian ghi trong Retry-After rồi đăng nhập lại với mật khẩu đúng. Một lần đăng nhập đúng xoá bộ đếm. Giao diện nên hiện câu báo của server, đừng tự thử lại liên tục.

Form công khai trả 429 RATE_LIMITED

Nguyên nhân. Handler ghi dữ liệu để công khai chỉ nhận 30 lần trong 10 phút từ một IP. Nhiều người dùng chung mạng văn phòng có chung một IP.

Cách sửa. Nâng mức cho handler đó, hoặc tắt cho webhook từ hệ thống khác:

app/orders/post.ts
export const access = "public"; export const rateLimit = { max: 200, windowSec: 600 };

Dữ liệu

Dữ liệu như biến mất sau khi đổi tên cột

Nguyên nhân. Deploy chỉ thêm, không xoá cũng không đổi tên. Đổi tên cột trong .table.ts tạo một cột mới rỗng. Dữ liệu cũ vẫn nằm ở cột cũ, nhưng code không đọc cột đó nữa.

Cách sửa. Đổi lại tên cũ trong code để dữ liệu hiện lại. Nếu vẫn muốn đổi tên: thêm cột mới, chép dữ liệu bằng một câu UPDATE, chuyển code sang cột mới, rồi mới bỏ cột cũ.

manh.run không giữ bản sao lưu database. Quay lại bản code cũ không đưa dữ liệu về. Trước mỗi câu UPDATE hay DELETE, chạy cùng điều kiện WHERE bằng SELECT COUNT(*) để biết bao nhiêu dòng sẽ đổi. Trước thay đổi lớn, xuất bảng ra CSV ở mục Cơ sở dữ liệu của project.

Xoá bản ghi báo FOREIGN KEY constraint failed

Nguyên nhân. Khoá ngoại được kiểm thật. Xoá một khách còn đơn hàng, hoặc thêm đơn cho khách không tồn tại, đều bị database từ chối.

Cách sửa. Chọn onDelete có chủ đích trong .references(…): "cascade", "set null" hoặc "restrict". Trong repository, kiểm tra bản ghi con trước và trả 409 với câu dễ hiểu, ví dụ “Khách còn đơn hàng, không xoá được”.

Dữ liệu mẫu bị nhân đôi

Nguyên nhân. Đoạn tạo dữ liệu mẫu chạy nhiều lần, mỗi lần thêm một bộ mới.

Cách sửa. Đếm số dòng trước khi thêm, và chỉ thêm khi bảng còn trống. Xoá dữ liệu thử theo id của chính các dòng đã tạo, không xoá theo điều kiện rộng.

Giờ lệch 7 tiếng

Nguyên nhân. Server lưu và tính giờ theo UTC. Việt Nam là UTC+7.

Cách sửa. Định dạng ngày giờ cho người đọc bằng manh/vn. Lịch cron cũng theo UTC: 8 giờ sáng Việt Nam là 0 1 * * *.

Cron, email, Telegram

Cron không chạy

Nguyên nhân. Hay gặp nhất:

  • Lịch viết theo giờ Việt Nam trong khi cron chạy theo UTC.
  • File không tên *.cron.ts, hoặc thiếu export const schedule.
  • App chưa deploy. Cron chỉ chạy trên app đã deploy, không chạy trong bản xem trước.
  • Lần chạy ném lỗi. manh.run thử lại tối đa 3 lần, rồi ghi lỗi vào nhật ký.

Cách sửa. Kiểm tra lịch và tên file, deploy, rồi xem Nhật ký. Viết việc sao cho chạy lại không làm sai dữ liệu. Xem *.cron.ts.

Email không tới

Nguyên nhân.

  • Địa chỉ người nhận là địa chỉ mẫu (example.com, .test, .invalid, .example). manh.run không gửi, email() trả { ok: false, skipped: true } và nhật ký có dòng [email] FAILED … demo address.
  • Đã hết hạn mức email ngày hoặc tháng: BUILTIN_QUOTA_EXCEEDED.
  • Code gọi email() trước khi ghi database, rồi request lỗi giữa chừng.
  • Thư nằm trong hộp thư rác của người nhận.

Cách sửa. Mở Nhật ký: mỗi lần gửi để lại một dòng [email] sent hoặc [email] FAILED kèm lý do. Kiểm tra ok trong kết quả trước khi báo “Đã gửi”. Gọi email() sau khi ghi xong, trong try/catch. Xem Email.

Bot Telegram im lặng

Nguyên nhân.

  • Chủ app chưa nối bot ở Kết nối › Telegram của project. send và linkUrl ném lỗi “Telegram is not connected”.
  • Người nhận chưa bấm Start qua link riêng, nên app chưa lưu chatId của họ.
  • Hàm trong *.telegram.ts ném lỗi. Lỗi vào nhật ký và Telegram không gửi lại, nên người dùng không nhận gì.
  • Người nhận đã chặn bot. Lỗi khi gửi có err.blocked === true.

Cách sửa. Nối bot, rồi bảo người dùng bấm nút nhận thông báo trong app. Bắt lỗi trong hàm và trả một câu dễ hiểu. Xem *.telegram.ts.

AI không đọc được ảnh hay PDF scan

Nguyên nhân. manh/openai chỉ có model chữ. Không có đọc ảnh, âm thanh hay file: BUILTIN_UNSUPPORTED.

Cách sửa. Chỉ gửi văn bản. Với chứng từ giấy, để người dùng nhập các trường chính, rồi dùng AI kiểm tra hoặc tóm tắt phần chữ.

Bước tiếp theo

  • Nhật ký — xem lỗi server, lần chạy cron và email đã gửi của app.
  • Rollback và checkpoint — đưa app về bản chạy tốt gần nhất rồi sửa tiếp.
  • Mã lỗi — tra một mã lỗi cụ thể và cách xử lý.
Cập nhật