Mã lỗi
Các mã lỗi bạn và agent gặp trên manh.run, gồm lỗi API của app trả về, mã luật của check và lỗi khi deploy, kèm nghĩa và cách sửa.
Trang chia theo nơi lỗi hiện ra: response của API, kết quả check, kết quả deploy. Mã trên trang này là mã thật trong code của manh.run. Bạn dựa vào chúng để viết giao diện rẽ nhánh theo lỗi.
Dạng một lỗi API
Mọi lỗi 4xx của API app có cùng một dạng JSON:
{ "error": "Không tìm thấy đơn", "message": "Không tìm thấy đơn", "code": "NOT_FOUND" }messagelà câu cho người dùng đọc.errorlặp lạimessageđể code cũ vẫn đọc được.codelà mã cố định, dùng để rẽ nhánh trong giao diện. Lỗi không có mã thì không có trường này.- Handler ném lỗi không lường trước thì app trả 500 với
{ "error": "INTERNAL", "message": "Máy chủ gặp lỗi, vui lòng thử lại sau.", "code": "INTERNAL" }. Lỗi gốc nằm trong nhật ký của app, người dùng không thấy. - Lỗi 5xx bạn chủ động trả kèm mã, ví dụ
fail(503, "Hệ thống đang bảo trì, quay lại sau 10 phút", "MAINTENANCE"), tới người dùng nguyên văn với status đó.
Trong code của app, dừng request bằng fail với mã riêng của bạn:
import { fail } from "manh/errors";
if (!product) fail(404, "Sản phẩm không tồn tại", "NOT_FOUND");
if (product.stock < qty) fail(409, `Chỉ còn ${product.stock} sản phẩm`, "OUT_OF_STOCK");Lỗi framework trả về
Những lỗi này đến trước khi handler của bạn chạy, hoặc từ hàm có sẵn của framework.
| Status | code | Khi nào | Cách xử lý |
|---|---|---|---|
| 400 | validation | Body hoặc query sai schema của handler. Response có thêm fields (tên trường → câu lỗi tiếng Việt) và issues. Handler không chạy. | Hiện fields cạnh ô nhập tương ứng. Nếu dữ liệu đúng mà vẫn lỗi, sửa schema. |
| 401 | UNAUTHENTICATED | Gọi handler cần đăng nhập khi chưa đăng nhập, phiên đã hết hạn (7 ngày) hoặc tài khoản đã bị khoá. | Đưa người dùng về trang đăng nhập. Handler ai cũng gọi được thì đặt export const access = "public". |
| 403 | FORBIDDEN | Vai của người dùng không nằm trong access, hoặc không được phép đi bước chuyển trạng thái đó. | Kiểm tra access của handler và vai trong app/auth.ts. |
| 409 | FLOW_ILLEGAL | Chuyển trạng thái không có trong luồng đã khai báo, ví dụ từ “Đã huỷ” sang “Đã giao”. | Chỉ hiện nút cho các bước hợp lệ từ trạng thái hiện tại. |
| 429 | RATE_LIMITED | Handler ghi dữ liệu (POST, PUT, PATCH, DELETE) để công khai bị gọi quá 30 lần trong 10 phút từ cùng một IP. Có header retry-after. | Đổi mức bằng export const rateLimit = { max, windowSec }, tắt bằng export const rateLimit = false cho webhook từ hệ thống khác. |
| 502 | UPSTREAM_NOT_CONFIGURED, UPSTREAM_UNREACHABLE | App đứng trước hệ thống cũ qua app/upstream.ts: đường dẫn chưa khai báo, hoặc hệ thống cũ không trả lời. | Xem app/upstream.ts. |
Lỗi đăng nhập
Các lỗi này đến từ đăng nhập sinh sẵn theo app/auth.ts.
| Status | code | Nghĩa |
|---|---|---|
| 401 | INVALID_CREDENTIALS | Sai email hoặc mật khẩu. Câu báo giống nhau cho cả hai trường hợp, để không lộ email nào đã có tài khoản. |
| 401 | ACCOUNT_LOCKED | Tài khoản đăng nhập bằng Google đã bị quản trị viên khoá. |
| 403 | SIGNUP_CLOSED | App không mở đăng ký. Quản trị viên tạo tài khoản ở trang người dùng. |
| 409 | EMAIL_TAKEN | Email đã được đăng ký. |
| 409 | SELF_CHANGE | Quản trị viên tự đổi vai hoặc tự khoá tài khoản của mình. |
| 400 | SSO_PROVIDER_OFF | App chưa bật đăng nhập bằng nhà cung cấp đó trong providers. |
| 429 | TOO_MANY_ATTEMPTS | Sai mật khẩu 5 lần với một email, hoặc 30 lần từ một IP, trong 15 phút. Có retry-after. |
Lỗi của runtime
manh.run trả các lỗi dưới đây khi app quá tải hoặc chạm hạn mức của gói. Cả nhóm dùng chung một dạng body:
{ "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" }codelà mã lỗi.errormang cùng giá trị, giữ lại cho code cũ đang đọc trường này.retryablecho biết gọi lại sau một lúc có thể thành công hay không. Hết hạn mức tháng thìfalse.retryAfterSecondsbằng headerRetry-After, tính bằng giây.requestIdbằng headerX-Request-ID. Mọi response của API đều có header này, và handler đọc được nó quac.req.header("x-request-id"). Khi báo lỗi cho manh.run, gửi kèm mã này.
429 nghĩa là chạm hạn mức, 503 là đang bận, 504 là dịch vụ phía sau trả lời quá lâu.
useApiClient() và useApi() tự gọi lại khi gặp lỗi có retryable: true: đợi đúng Retry-After, nếu không có thì lùi dần có ngẫu nhiên, tối đa 3 lần, không đợi quá 8 giây. Lệnh đọc (GET) luôn được gọi lại. Lệnh ghi (POST, PUT, PATCH, DELETE) chỉ được gọi lại khi có khoá chống trùng: api.orders.create(body, { idempotencyKey }), xem useApiClient. Lỗi cuối cùng vẫn tới trang, với error.ftCode và error.requestId.
| Status | error | Nghĩa | Cách xử lý |
|---|---|---|---|
| 429 | RATE_LIMITED | App nhận nhiều request mỗi phút hơn mức của gói. retry-after chỉ tới hết phút. | Giảm số lần gọi lặp (gộp request, bỏ polling dày). Mức từng gói xem ở Hạn mức theo gói. |
| 503 | CPU_LIMIT | Một route dùng quá CPU cho mỗi request 3 lần trong 1 phút, nên bị tạm chặn 60 giây. Route khác vẫn chạy. Chủ app nhận một email báo. | Tìm vòng lặp hoặc truy vấn nặng trong route đó. Việc dài chuyển sang việc nền. |
| 503 | APP_BUSY | App đang quá tải. retry-after: 1. | Client tự thử lại. Nếu lặp lại thường xuyên, xem request nào chậm trong nhật ký. |
| 503 | EGRESS_BUSY | Lời gọi ra ngoài của app (fetch tới dịch vụ khác) không đi được vì đường ra đang bận. Handler nhận response 503 này thay vì lỗi ném ra. | Trả lỗi cho người dùng hoặc đưa việc sang việc nền để chạy lại sau. |
| 503 | APP_ERROR | App không trả lời, thường vì lỗi khi khởi động. | Mở Nhật ký để xem lỗi, sửa rồi deploy lại. |
| 503 | APP_SUSPENDED | App đang tạm dừng, ví dụ project đã chuyển vào thùng rác. | Khôi phục project rồi deploy lại. |
| 429 | TOO_MANY_CONNECTIONS | Số kết nối trực tiếp đang mở vượt mức của gói. | Đóng kết nối ở trang không còn mở. |
Hết hạn mức tháng (số request, dung lượng database) không làm app dừng. manh.run gửi email cảnh báo cho chủ app ở mức 80% và 100%.
Lỗi của dịch vụ có sẵn
manh/email và manh/openai ném lỗi có status và mã dưới đây. Bọc lời gọi trong try/catch để việc chính của request không hỏng theo.
| Status | Mã | Nghĩa |
|---|---|---|
| 429 | BUILTIN_QUOTA_EXCEEDED | Đã dùng hết email (theo ngày hoặc tháng) hoặc token AI (theo tháng) của gói. Tính chung mọi app của tài khoản. App vẫn chạy. |
| 400 | EMAIL_TOO_MANY_RECIPIENTS | Một email có hơn 10 người nhận (to + cc + bcc). Gửi từng người một. |
| 400 | BUILTIN_MODEL_NOT_ALLOWED | Tên model AI không có. Dùng gpt-4o-mini, gpt-4o hoặc text-embedding-3-small. |
| 413 | BUILTIN_TOO_LARGE | Body gửi AI lớn hơn 256 KB. Chỉ gửi phần văn bản cần cho việc đó. |
| 501 | BUILTIN_UNSUPPORTED | Tính năng AI không có: ảnh, âm thanh, file. Chỉ có hội thoại và embedding. |
| 424 | SUPABASE_NOT_CONNECTED | App gọi Supabase khi chủ app chưa kết nối. Xem Supabase. |
Mã luật của check
check trả mỗi lỗi kèm mã luật, file và dòng. Bảng dưới là các mã agent hay gặp nhất. Danh sách đầy đủ theo nhóm ở Quy tắc check; cách đọc một dòng lỗi ở Đọc lỗi check.
| Mã | Nghĩa | Cách sửa |
|---|---|---|
code.syntax-error | File không phân tích được. | Viết lại file, đếm ngoặc mở và đóng. Sửa lỗi này trước, vì nó tạm dừng phần lớn luật khác. |
code.undefined-component | Dùng <Tên /> chưa import hay khai báo. | Thêm import. Không sửa thì trang hỏng với ”… is not defined”. |
ui.unknown-icon | Tên icon không có trong @ant-design/icons. | Dùng tên có thật (đuôi Outlined, Filled, TwoTone); thông báo gợi ý tên gần nhất. |
code.antd-v6-no-visible-prop | visible trên Modal, Drawer… của antd v6. | Đổi thành open. |
code.invalid-api-method | Gọi api.<tài nguyên>.<hàm>() không có trong client sinh sẵn. | Dùng một hàm trong danh sách thông báo đưa ra, hoặc thêm handler. |
code.api-namespace-called-as-function | Gọi api.orders(...) như một hàm. | Gọi hàm con, ví dụ api.orders.create(body). |
code.frontend-subpath-unavailable | File .tsx import một đường dẫn con của package mà app không có. | Import từ tên package gốc. |
code.no-app-api-folder | File nằm trong app/api/. | Chuyển về app/<tài nguyên>/<method>.ts. |
code.no-framework-file-emit | Viết tay app/db.ts, app/api.ts hay app/hooks.ts. | Xoá file đó. Bảng khai báo trong <tài nguyên>.table.ts. |
DUPLICATE_PAGE, DUPLICATE_HANDLER, DUPLICATE_CRON | Hai file cùng ra một URL, cùng một method và đường dẫn, hoặc hai việc cron trùng tên. | Gộp hoặc đổi tên một trong hai. |
code.runtime-import | Import runtime khác import { env } from "manh/env". | Đọc secret qua env.NAME. |
code.backend-package-not-allowed, code.package-denied | Package không có trong danh sách server, hoặc bị cấm. | Dùng package trong danh sách mà thông báo liệt kê, xem Phiên bản. |
code.backend-import-unresolved | Import trong file .ts trỏ tới file không có, hoặc chỉ có bản .tsx. | Sửa đường dẫn. Hàm dùng chung cho cả hai bên đặt trong app/shared. |
code.no-remote-import, code.no-npm-specifier | Import bằng URL hoặc npm:…@phiên-bản. | Import bằng tên package, không ghi phiên bản. |
code.unknown-std-import | Import manh/<tên> không có. | Dùng một module có sẵn trong app/std. |
code.no-async-transaction | db.transaction(async …). | Kiểm tra mọi điều kiện trước, rồi mới ghi. |
code.no-dayjs-in-backend | Dùng dayjs trong file .ts. | Dùng Date, hoặc manh/vn cho giờ Việt Nam. |
code.hardcoded-secret, code.no-reserved-env | Khoá API viết thẳng trong code, hoặc đọc tên dành riêng như OPENAI_API_KEY. | Đặt secret trong dashboard. Dịch vụ có sẵn không cần khoá. |
code.jwt-verify-alg | verify(token, secret) thiếu "HS256". | Thêm tham số thứ ba "HS256". |
auth.config-invalid, access.unknown-role | app/auth.ts sai dạng, hoặc access nêu một vai không có trong roles. | Sửa theo thông báo; vai phải viết cố định. |
code.cron-missing-schedule, code.cron-invalid-schedule | File .cron.ts thiếu schedule, hoặc lịch không đủ 5 trường. | Thêm export const schedule = "0 1 * * *" (giờ UTC). |
Lỗi khi deploy
Agent nhận các lỗi này dưới dạng một dòng chữ mở đầu bằng mã.
| Mã | Nghĩa | Cách xử lý |
|---|---|---|
CHECK_FAILED | check còn lỗi nên deploy bị từ chối. Danh sách lỗi đi kèm. | Sửa rồi deploy lại. Nếu chỉ còn lỗi kiểu hoặc lỗi hiển thị và bạn chắc app vẫn chạy, agent gọi deploy({ force: true, reason }). |
FORCE_NEEDS_REASON | Có force: true mà thiếu reason (ít nhất 5 ký tự). | Ghi lý do vì sao các lỗi đó không ảnh hưởng app. |
PLAN_LIMIT | App có nhiều việc cron hơn mức gói, hoặc tài khoản có nhiều project hơn mức gói. Khi đó chỉ các project deploy gần nhất được deploy tiếp. | Gộp các việc chạy cùng lịch vào một file, hoặc xoá bớt project. App đang chạy giữ nguyên. |
CRON_TOO_MANY_SCHEDULES | Hơn 20 lịch cron khác nhau trong một app. | Gộp các việc chạy cùng lịch. |
CHECKPOINT_LIMIT | Project đã có 100 checkpoint đặt tên. | Xoá checkpoint cũ ở tab Deploy & lịch sử. |
TOOL_FAILED | Lỗi không lường trước. Không có gì thay đổi, trừ khi thông báo nói khác. | Thử lại một lần. Lặp lại thì xem trạng thái project và Nhật ký. |
Một cây file đã từng deploy thành công luôn deploy lại được, kể cả khi check nay báo lỗi. Nhờ vậy việc quay lại bản cũ không bao giờ bị chặn.
Lệnh database của agent có thêm vài mã: ENV_NOT_PROVISIONED (project chưa deploy nên chưa có database), READ_ONLY (gửi câu ghi qua lệnh chỉ đọc), NOT_A_WRITE (gửi câu đọc qua lệnh ghi) và INTERNAL_TABLE (ghi vào bảng hệ thống của manh.run).
Lệnh kiểm thử có thêm: NO_TESTS (chưa có spec/acceptance.json), BAD_TESTS (file sai dạng, kèm chỗ sai), NOT_DEPLOYED (bài kiểm tra cần app đã deploy), NO_SIGN_IN (bước dùng as mà app không có app/auth.ts) và UNKNOWN_ROLE (vai không có trong app/auth.ts). Lệnh ảnh trả NO_IMAGE khi thiếu cả link lẫn file.
Deploy không xoá cột hay bảng, và không đổi kiểu cột. Ghi chú của lần deploy báo hai trường hợp cần đọc kỹ: cột mới .notNull() không có .default() được thêm dưới dạng cho phép rỗng, và index unique không tạo được vì dữ liệu đang trùng. Database không có bản sao lưu, nên đọc ghi chú trước khi sửa dữ liệu bằng tay.
Bước tiếp theo
- Quy tắc check: mọi luật theo nhóm.
- Hạn mức theo gói: số request, CPU, email và AI của từng gói.
- Khắc phục sự cố: triệu chứng hay gặp và cách sửa.