# Khắc phục sự cố

> Chưa thấy lỗi, lỗi bị chặn bởi CSP, lỗi trùng, giới hạn 429, node mất kết nối và vấn đề đăng nhập — kiểm tra từng bước.

Làm theo mục khớp với điều bạn đang thấy. Phần lớn vấn đề được tìm ra trong ba bước kiểm tra đầu tiên.

## Không thấy lỗi nào về

### 1. SDK có đang chạy không?

- `init` trả về `true` khi đang chạy. Tạm thêm `debug: true`: SDK sẽ ghi các quyết định của nó ra console, kể cả khi DSN sai.
- DSN phải là DSN của đúng project này, sao chép nguyên vẹn: `https://<public-key>@ingest.belvador.dev/<project-id>`. Không có dấu nháy bên trong, không có dấu `/` ở cuối.
- `disabled: true`, `BELVADOR_DISABLED=1` hoặc `sampleRate: 0` sẽ tắt việc gửi.

### 2. Request có rời khỏi ứng dụng không?

Trên trình duyệt, mở tab Network và tạo một lỗi thử. Tìm request `POST` tới `https://ingest.belvador.dev/api/<project-id>/envelope/`.

- **Không có request nào** — lỗi đã bị bắt trước khi SDK thấy (xem [Lỗi do framework xử lý](#loi-do-framework-xu-ly-khong-bao-gio-ve)), hoặc `init` chưa chạy.
- **Bị CSP chặn** — console báo vi phạm `Content-Security-Policy`. Thêm `https://ingest.belvador.dev` vào `connect-src`.
- **Bị trình chặn quảng cáo hoặc chặn theo dõi chặn** — request thất bại, không có mã trạng thái. Thử bằng một hồ sơ trình duyệt sạch.

### 3. Edge trả lời gì?

| Mã | Ý nghĩa | Cách sửa |
|---|---|---|
| `200` | Đã nhận. Tiếp tục bước 4. | — |
| `401` | Thiếu khoá hoặc khoá sai | Sao chép lại DSN từ project; khoá có thể đã bị thu hồi |
| `403` | Sai project, bị từ chối, hoặc **origin không được phép** | Thêm website vào **Tên miền cho phép** hoặc để trống danh sách — xem [Project và DSN](https://belvador.dev/vi/docs/projects-and-dsn#ten-mien-cho-phep) |
| `413` | Quá lớn | Một event tối đa 1 MiB, một tệp đính kèm tối đa 5 MiB |
| `415` | Kiểu nén không hỗ trợ | Dùng SDK Belvador hoặc SDK Sentry bản hiện hành |
| `429` | Vượt giới hạn tốc độ, vượt hạn mức tháng, hoặc vùng đệm của node đã đầy | Xem header `Retry-After`; xem [Giới hạn](#429-qua-nhieu-request) |
| `503` | Edge gặp sự cố tạm thời | SDK tự thử lại |

Sau `401` hoặc `403`, SDK của Belvador ngừng gửi trong suốt vòng đời của trang hoặc isolate Worker đó — tải lại trang sau khi sửa.

### 4. Đã nhận nhưng không thấy?

- Xem **Cài đặt project → Lượng lỗi nhận 24 giờ qua**: nếu **Đã nhận** tăng, lỗi đã tới Belvador.
- **Node có Khoẻ không?** Nếu **Mất kết nối**, lỗi được giữ ở edge và sẽ hiện khi node kết nối lại — xem [Sức khoẻ node](https://belvador.dev/vi/docs/node/health#khi-node-mat-ket-noi).
- Kiểm tra bộ lọc issue: mặc định là trạng thái **Chưa xử lý** và khoảng **24 giờ**, và bộ lọc môi trường có thể đang ẩn môi trường của bạn.
- Đó có phải dữ liệu tracing hay session chứ không phải lỗi? Những thứ đó được đếm vào **Chưa hỗ trợ** và không được lưu.

### Tab Kết nối báo Chưa kiểm hoặc Đang có vấn đề

**Chưa kiểm** nghĩa là chưa có phép kiểm kết nối nào tới — chạy phép kiểm cho nền tảng của bạn trong [Kiểm tra kết nối](https://belvador.dev/vi/docs/sdk/verify). **Đang có vấn đề** liệt kê điều gì sai và cần làm gì; mọi mã đều được giải thích ở trang đó. Khi bật `debug: true`, SDK cũng in mã chẩn đoán trong console.

### Kiểm đường nhận không bao giờ tới

**Kiểm đường nhận** ở tab Kết nối gửi một event từ node qua đường nhận lỗi công khai; nó không kiểm app. Nếu sau khoảng 10 giây vẫn chưa tới, thường là node chưa kết nối: mở **Node** và xem trạng thái.

## Lỗi do framework xử lý không bao giờ về

Framework thường bắt lỗi để hiện màn hình lỗi đẹp — khi đó SDK không bao giờ thấy lỗi.

| Ở đâu | Cần nối gì |
|---|---|
| Lỗi render React | `ErrorBoundary`, và với React 19 thêm ba root hook — [React](https://belvador.dev/vi/docs/sdk/react) |
| Màn hình lỗi của router (`errorElement` của React Router, …) | `captureException(error)` bên trong màn hình lỗi |
| Lỗi route của TanStack Start | `createRouter(withBelvadorRouter({ ... }))` — [TanStack Start](https://belvador.dev/vi/docs/sdk/tanstack-start) |
| Error hook của Vue, Angular, Svelte | `captureException` từ error hook của framework |
| `try … catch` của bạn | `captureException(error)` ở chỗ bạn vẫn muốn biết |

## TanStack Start: chỉ thấy lỗi trình duyệt

- `belvadorRequestMiddleware` và `belvadorFunctionMiddleware` phải nằm **cuối** `requestMiddleware` và `functionMiddleware`.
- `src/server.ts` phải bọc đúng entry đang phục vụ request, và `vite.config.ts` phải trỏ `tanstackStart.server.entry` tới đó.
- Worker cần `nodejs_compat`.
- Không báo theo thiết kế: `redirect()`, `notFound()`, lỗi có mã dưới 500, và response 500 bạn tự trả về mà không ném lỗi.
- Lỗi trong loader của route khi render trên máy chủ thường chỉ được báo từ trình duyệt — đây là giới hạn đã biết.

## Mỗi lỗi về hai lần

- Cài đặt `@sentry/*` cũ hoặc lời gọi `Sentry.init` vẫn chạy song song với Belvador. Hãy gỡ đi.
- Cùng một lỗi được hai hook của bạn báo, ví dụ một `try … catch` gọi `captureException` rồi ném lại lỗi lên một boundary cũng báo. Chỉ báo ở một chỗ.
- Hai project cùng nhận một ứng dụng vì có hai DSN được cấu hình ở hai file khác nhau.

## Lỗi bị gom nhóm sai

- **Quá nhiều issue riêng** cho một bug: message chứa giá trị mà Belvador không chuẩn hoá — đặt [fingerprint](https://belvador.dev/vi/docs/issues#tu-dat-cach-gom-nhom).
- **Nhiều bug khác nhau trong một issue**: chúng dùng chung một stack, ví dụ một hàm xử lý lỗi chung. Báo với fingerprint hoặc loại exception cụ thể hơn.

## Stack trace hiện code thu nhỏ

Xem [Source map](https://belvador.dev/vi/docs/source-maps#kiem-tra): `release` phải khớp, file đã triển khai phải là bản đã ghi Debug ID, và việc tải lên phải thành công.

## Dữ liệu nhạy cảm xuất hiện trong event

1. **Đổi bí mật bị lộ trước tiên.** Xoá khỏi Belvador không làm mất việc nó đã bị lộ.
2. Kiểm tra **Project → Quyền riêng tư → Bộ dò có sẵn**: mọi nhóm nên được bật.
3. Tìm xem nó đến từ đâu — tag, ngữ cảnh, message hay tệp đính kèm — rồi ngừng gửi, hoặc bỏ đi trong `beforeSend`.
4. Đọc [những gì bộ lọc không đảm bảo](https://belvador.dev/vi/docs/privacy#nhung-gi-bo-loc-khong-dam-bao).

## 429: quá nhiều request

| Lý do | Điều gì xảy ra | Cách sửa |
|---|---|---|
| `rate_limited` | Vượt **Event mỗi giây** hoặc **Cụm tối đa** của project | Thường là một vòng lặp báo cùng một lỗi — sửa nó, hoặc nâng giới hạn project tới mức của gói |
| `quota_exceeded` | Workspace đã dùng hết hạn mức envelope của tháng | Việc gửi tiếp tục từ đầu tháng sau (giờ UTC) |
| `buffer_full` | Node mất kết nối và vùng đệm ở edge đã đầy | Đưa node trở lại — [Sức khoẻ node](https://belvador.dev/vi/docs/node/health#khi-node-mat-ket-noi) |

## Monitor không có lượt chạy nào

1. Chạy job một lần và xem output: với `debug: true` SDK ghi `BLV_MONITOR_INVALID_SLUG`, `BLV_MONITOR_INVALID_REASON` hoặc `BLV_MONITOR_CONFIG_INVALID` khi từ chối gửi.
2. Kiểm slug trên trang Monitor khớp từng ký tự với slug trong code, và cùng project.
3. Check-in từ trình duyệt bị từ chối có chủ đích. Hãy gửi từ máy chủ hoặc bằng `curl` — xem [Check-in qua HTTP](https://belvador.dev/vi/docs/monitors/http).
4. Với `curl`, đọc mã trả về: `401` là sai khoá hoặc sai project, `429` là bị giới hạn tốc độ.
5. Slug chưa thành monitor sẽ hiện ở **Phát hiện từ code** khi project không cho tạo monitor từ code.

## Monitor ghi Không quan sát được

Belvador không theo dõi được khoảng thời gian đó: node mất kết nối hoặc đang bắt kịp, hoặc check-in bị giới hạn tốc độ hay vượt hạn mức tháng. Các lượt trong khoảng đó không bị tính là lỡ. Khi node trở lại, nó chờ tối đa 10 phút để nhận check-in còn đợi, rồi đánh giá lại. Xem [Khi Belvador không nhìn thấy](https://belvador.dev/vi/docs/monitors/overview).

## Monitor ghi Bị lỡ nhưng job đã chạy

- Job có thể báo về **môi trường** khác với môi trường monitor theo dõi: xem các tab môi trường trên monitor.
- Múi giờ của lịch có thể khác múi giờ của trình lập lịch. Form tạo monitor hiện các hạn kế tiếp theo cả múi giờ của monitor và của bạn.
- Biên độ có thể quá ngắn so với độ trễ khởi động của job; hãy tăng **Biên độ**.

## 429 với check-in

Check-in có giới hạn riêng, tách khỏi lỗi: 60 mỗi monitor và môi trường mỗi phút, cộng hạn mức tháng theo gói. Vòng lặp gửi một check-in cho mỗi phần tử nên chuyển sang một heartbeat mỗi lô — xem [Theo dõi việc chạy ngầm](https://belvador.dev/vi/docs/guides/background-work).

## Lỗi CORS sau khi bật trace

API ở origin khác phải cho phép `traceparent` và `sentry-trace` trong `Access-Control-Allow-Headers`. Thu hẹp `tracePropagation.targets` về API của chính bạn, hoặc cho phép các header — xem [Liên kết lỗi qua nhiều tầng](https://belvador.dev/vi/docs/sdk/tracing).

## Node không khoẻ

Xem [Sức khoẻ node](https://belvador.dev/vi/docs/node/health) cho mọi trạng thái và lý do. Nếu máy đã mất, dùng **Thay máy & khôi phục** — [Cập nhật và dựng lại](https://belvador.dev/vi/docs/node/updates#thay-may-va-khoi-phuc).

## Đăng nhập và xác thực 2 lớp

- **“Phiên đăng nhập đã hết. Hãy đăng nhập lại.”** — đăng nhập lại; phiên có thời hạn.
- **Mất ứng dụng xác thực** — dùng mã khôi phục trên màn hình nhập mã: [Bảo mật tài khoản](https://belvador.dev/vi/docs/account-security#mat-dien-thoai).
- **“Mã không đúng hoặc đã hết hạn.”** — kiểm tra đồng hồ điện thoại đang đặt tự động; mã phụ thuộc vào thời gian.
- **“Thao tác này cần xác thực 2 lớp.”** — bật xác thực 2 lớp trong Bảo mật tài khoản, rồi thử lại.

## Thông báo có thể gặp

| Thông báo | Ý nghĩa |
|---|---|
| Node chưa sẵn sàng. Thử lại khi trạng thái là Khoẻ. | Thao tác cần một node đang chạy |
| Node đang mất kết nối… | Node sẽ nhận yêu cầu khi kết nối lại |
| Khoảng thời gian quá lớn để đọc nhanh. | Thu hẹp khoảng thời gian hoặc bộ lọc |
| Workspace đã đạt giới hạn cho mục này. | Một giới hạn của gói, ví dụ số workspace |
| Project chưa có khoá DSN nào đang hoạt động. | Tạo khoá trong Cài đặt project → Khoá DSN |
| Node không gửi được lỗi thử qua đường nhận lỗi. | Kiểm tra node còn kết nối ở trang Node |
| Quá nhiều yêu cầu. Đợi một chút rồi thử lại. | Quá nhiều thay đổi trong thời gian ngắn |

Lỗi trong ứng dụng có kèm mã tham chiếu. Nếu liên hệ hỗ trợ qua hello@belvador.dev, hãy gửi kèm mã đó — không bao giờ gửi token, mật khẩu hay mã khôi phục.