Xử lý sự cố

Triệu chứng thường gặp, nguyên nhân thật và cách sửa. Tra theo khu vực.

Cài đặt

404 Not Found khi pnpm install package @tasco/*

.npmrc đang trỏ instance endpoint. Scope @tasco phải trỏ group endpoint:

@tasco:registry=https://gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/
//gitlab.dnpwater.vn/api/v4/groups/tasco/-/packages/npm/:_authToken=${NPM_TOKEN}

Vẫn 404 sau khi sửa: token đang là PAT cá nhân của người chưa phải thành viên group. Dùng Group Deploy Token scope read_package_registry.

401 Unauthorized

Dòng authToken phải bắt đầu bằng //, không có https:. Kiểm tra token có giá trị:

echo $NPM_TOKEN

ERR_PNPM_IGNORED_BUILDS

pnpm 11 chặn build script của dependency cho tới khi có quyết định tường minh. Chép khối allowBuilds từ pnpm-workspace.yaml của template CLI, hoặc:

pnpm approve-builds

Chạy dev

<CTable> báo unknown component, useApi không tự import

Layer chưa được nạp. Kiểm tra nuxt.config.ts có extends: ['@tasco/nuxt-layer-base'], rồi:

npx nuxi info      # phải thấy layer trong danh sách

Lỗi tsconfig hoặc thiếu kiểu sau khi cài mới

npx nuxi prepare   # sinh lại .nuxt/tsconfig.json

Vẫn lỗi thì xoá .nuxt rồi chạy lại — Vite giữ cache tsconfig hỏng cho tới khi khởi động lại server.

Sửa app.config.ts mà menu không đổi

Nuxt không phải lúc nào cũng nạp lại app.config.ts khi đang chạy — khởi động lại dev server. Menu vẫn thiếu mục thì kiểm tra permission của mục đó: không có quyền là mục bị ẩn hoàn toàn. Menu thừa mục lạ thì nhớ Nuxt nối mảng giữa các layer — một layer trung gian có sẵn nav sẽ cộng dồn vào menu của dự án (xem app.config › tasco).

Console báo "unhandled rejection" ngay khi mở trang danh sách

useTable tự tải lần đầu và không ai bắt lỗi của lần tải đó. Xử lý tường minh:

const { load } = useTable(fetchOrders, { immediate: false })
onMounted(() => load().catch($tascoError))

Đăng nhập

Đăng nhập xong vẫn bị đưa về trang đăng nhập

Kiểm tra	Cách xác minh
Cookie có được đặt không	DevTools → Application → Cookies, tìm tasco_session
Chạy HTTP ở môi trường không phải dev	Cookie đặt secure nên trình duyệt bỏ qua trên HTTP — phải dùng HTTPS
Nhiều instance sau load balancer	Tất cả phải dùng cùng NUXT_SESSION_SECRET
Cookie quá 4KB	Đừng nhét thêm dữ liệu vào phiên; xem Phiên đăng nhập
GET /auth/session trả { user: null }	Token hết hạn hoặc userInfo lỗi — xem tab Network

500 Session secret chưa cấu hình

Thiếu NUXT_SESSION_SECRET ở môi trường không phải dev:

openssl rand -base64 32

500 auth.baseURL chưa cấu hình (NUXT_AUTH_BASE_URL)

Thiếu biến, hoặc gõ sai tên. Quy tắc đặt tên: Cấu hình & biến môi trường.

IAM không trả accessToken (kiểm tra auth.mapping.token)

NUXT_AUTH_MAPPING_TOKEN trỏ sai đường dẫn trong response. Gọi thử endpoint login bằng curl rồi đối chiếu dot-path — xem Cấu hình IAM.

Đăng nhập được nhưng mọi trang trả 403

user.permissions rỗng hoặc không cùng dạng với URI khai trong definePageMeta. Mở GET /auth/session xem danh sách quyền thực nhận; kiểm tra MAPPING_PERMISSIONS, MAPPING_PERMISSION_KEY và bộ lọc MAPPING_PERMISSION_TYPE.

Gọi API

500 apiProxyTarget chưa cấu hình

Thiếu NUXT_API_PROXY_TARGET.

401 tuy vừa đăng nhập xong

Access token đã hết hạn (framework không tự gia hạn — token IAM sống 24 giờ), hoặc backend không chấp nhận token của IAM này. Kiểm tra expiresAt trong phiên bằng một route Nitro tạm thời, hoặc đăng nhập lại và thử ngay.

Backend không nhận được cookie của trình duyệt

Đúng như thiết kế: BFF xoá cookie và authorization do client gửi trước khi chuyển tiếp. Cần truyền gì sang backend thì đặt vào header khác trong route Nitro riêng.

Request treo rất lâu rồi mới lỗi

Route tự viết thiếu timeout. Mọi $fetch ra ngoài phải có timeout: 10_000.

Giao diện

Chế độ tối có chữ đen trên nền đen

CSS đang hardcode màu. Thay bằng var(--tasco-*) — xem Viết CSS trong dự án.

Trang nháy một nhịp không có định dạng, hoặc cảnh báo hydration trong console

Một route nào đó đang bật SSR trong khi dùng component antdv. Kiểm tra routeRules của dự án; bọc phần dùng Teleport/responsive trong <ClientOnly> — xem Chế độ render.

message / notification hiện sai màu

Chúng được gọi theo kiểu lệnh nên không lấy được theme khi chạy trên server. Chỉ gọi ở phía client, hoặc dùng App.useApp() của antdv trong route có SSR.

Font hiển thị sai ở lần build đầu

@nuxt/fonts tải font về lúc build; lần đầu cần mạng. Sau đó font nằm trong node_modules/.cache. Máy build không ra được Internet thì phải cache sẵn thư mục này.

Bảng nhiều cột vỡ bố cục trên màn hình hẹp

Cho bảng cuộn ngang thay vì ép xuống dòng:

<CTable :scroll="{ x: 1200 }" />

Build và deploy

Docker build hỏng ở bước cài package

NPM_TOKEN chưa được truyền dạng BuildKit secret. Xem CI/CD & Deploy và kiểm tra biến CI/CD đã đánh dấu Masked và Protected cho nhánh tương ứng.

vue-tsc báo lỗi type mới sau khi nâng phiên bản @tasco/*

Bản mới bổ sung khai báo slot và prop chặt hơn, nên lỗi type vốn có ở dự án lộ ra. Sửa theo thông báo; xem Nâng cấp phiên bản để biết thay đổi của từng bản.

App chạy được ở dev nhưng lỗi trắng sau khi build

Kiểm tra theo thứ tự: biến môi trường ở môi trường chạy (thiếu NUXT_SESSION_SECRET là 500), NUXT_API_PROXY_TARGET có tới được từ trong container, và log node .output/server/index.mjs.

Vẫn không xử lý được

1. Dựng lại lỗi trên playground của core hoặc một app scaffold mới — tách được lỗi của dự án khỏi lỗi của framework.
2. Ghi lại: phiên bản @tasco/*, phiên bản Node/pnpm, các bước dựng lại, thông báo lỗi đầy đủ.
3. Mở issue ở repo core kèm thông tin trên.

Liên quan

• Biến môi trường & runtimeConfig — bảng biến đầy đủ.
• CI/CD & Deploy — hạ tầng triển khai.
• Nâng cấp phiên bản — thay đổi giữa các bản.