Skip to Content

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" }
  • message là câu cho người dùng đọc. error lặp lại message để code cũ vẫn đọc được.
  • code là 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:

app/orders/repository.ts
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.

StatuscodeKhi nàoCách xử lý
400validationBody 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.
401UNAUTHENTICATEDGọ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".
403FORBIDDENVai 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.
409FLOW_ILLEGALChuyể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.
429RATE_LIMITEDHandler 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.
502UPSTREAM_NOT_CONFIGURED, UPSTREAM_UNREACHABLEApp đứ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.

StatuscodeNghĩa
401INVALID_CREDENTIALSSai 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.
401ACCOUNT_LOCKEDTài khoản đăng nhập bằng Google đã bị quản trị viên khoá.
403SIGNUP_CLOSEDApp không mở đăng ký. Quản trị viên tạo tài khoản ở trang người dùng.
409EMAIL_TAKENEmail đã được đăng ký.
409SELF_CHANGEQuản trị viên tự đổi vai hoặc tự khoá tài khoản của mình.
400SSO_PROVIDER_OFFApp chưa bật đăng nhập bằng nhà cung cấp đó trong providers.
429TOO_MANY_ATTEMPTSSai 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" }
  • code là mã lỗi. error mang cùng giá trị, giữ lại cho code cũ đang đọc trường này.
  • retryable cho 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.
  • retryAfterSeconds bằng header Retry-After, tính bằng giây.
  • requestId bằng header X-Request-ID. Mọi response của API đều có header này, và handler đọc được nó qua c.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.

StatuserrorNghĩaCách xử lý
429RATE_LIMITEDApp 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.
503CPU_LIMITMộ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.
503APP_BUSYApp đ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ý.
503EGRESS_BUSYLờ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.
503APP_ERRORApp 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.
503APP_SUSPENDEDApp đ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.
429TOO_MANY_CONNECTIONSSố 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.

StatusMãNghĩa
429BUILTIN_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.
400EMAIL_TOO_MANY_RECIPIENTSMột email có hơn 10 người nhận (to + cc + bcc). Gửi từng người một.
400BUILTIN_MODEL_NOT_ALLOWEDTên model AI không có. Dùng gpt-4o-mini, gpt-4o hoặc text-embedding-3-small.
413BUILTIN_TOO_LARGEBody gửi AI lớn hơn 256 KB. Chỉ gửi phần văn bản cần cho việc đó.
501BUILTIN_UNSUPPORTEDTính năng AI không có: ảnh, âm thanh, file. Chỉ có hội thoại và embedding.
424SUPABASE_NOT_CONNECTEDApp 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ĩaCách sửa
code.syntax-errorFile 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-componentDù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-iconTê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-propvisible trên Modal, Drawer… của antd v6.Đổi thành open.
code.invalid-api-methodGọ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-functionGọi api.orders(...) như một hàm.Gọi hàm con, ví dụ api.orders.create(body).
code.frontend-subpath-unavailableFile .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-folderFile nằm trong app/api/.Chuyển về app/<tài nguyên>/<method>.ts.
code.no-framework-file-emitViế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_CRONHai 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-importImport runtime khác import { env } from "manh/env".Đọc secret qua env.NAME.
code.backend-package-not-allowed, code.package-deniedPackage 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-unresolvedImport 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-specifierImport 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-importImport manh/<tên> không có.Dùng một module có sẵn trong app/std.
code.no-async-transactiondb.transaction(async …).Kiểm tra mọi điều kiện trước, rồi mới ghi.
code.no-dayjs-in-backendDùng dayjs trong file .ts.Dùng Date, hoặc manh/vn cho giờ Việt Nam.
code.hardcoded-secret, code.no-reserved-envKhoá 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-algverify(token, secret) thiếu "HS256".Thêm tham số thứ ba "HS256".
auth.config-invalid, access.unknown-roleapp/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-scheduleFile .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ĩaCách xử lý
CHECK_FAILEDcheck 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_REASONCó 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_LIMITApp 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_SCHEDULESHơ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_LIMITProject đã có 100 checkpoint đặt tên.Xoá checkpoint cũ ở tab Deploy & lịch sử.
TOOL_FAILEDLỗ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

Cập nhật