> For the complete documentation index, see [llms.txt](https://codedao12.gitbook.io/n8n-nodes-ultimate/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codedao12.gitbook.io/n8n-nodes-ultimate/khac/common-errors.md).

# Các lỗi thường gặp

> Tổng hợp lỗi phổ biến khi dùng `n8n-nodes-ultimate` và cách xử lý nhanh.

## 1) `Unrecognized node type n8n-nodes-XXXXXX.YYYY`

### Trường hợp 1: Cache n8n chưa cập nhật sau khi update

* Restart n8n trước để nạp lại danh sách community node.
* Kiểm tra package vẫn xuất hiện trong **Settings → Community Nodes**.
* Chỉ gỡ/cài lại sau khi đã sao lưu volume/database và xác nhận đúng phiên bản cần cài. Workflow vẫn được lưu trong n8n, nhưng các bước dùng package sẽ không chạy khi node chưa tải được.

### Trường hợp 2: Cài sai package

* Kiểm tra lại tên gói đã cài.
* Gói đúng là: `n8n-nodes-ultimate`.

## 2) `XMLhttprequest is not a constructor`

* Lỗi này thường bắt nguồn từ một community node khác đã bật biến môi trường gây xung đột runtime.
* Cách test nhanh:
  * Tạm gỡ các node community liên quan `facebook`, `tiktok`.
  * Restart n8n và thử lại.
* Nếu lỗi biến mất, nguyên nhân nhiều khả năng đến từ node xung đột đó.

## 3) `Cannot find module 'mime-types'`, `form-data` hoặc `tough-cookie`

* Lỗi này thường xuất hiện khi cây dependency trong thư mục community nodes bị dở dang sau một lần update hoặc container bị dừng giữa chừng. Đây không phải lỗi workflow.
* Trước tiên hãy restart n8n, sau đó thử tải lại trang Community Nodes.
* Nếu vẫn lỗi, dừng n8n rồi làm mới npm cache. Các lệnh dưới đây không xóa database, volume, workflow hay credential:

```bash
# Cài trực tiếp trên máy chủ
npm cache verify
npm cache clean --force

# Docker (thay đúng tên container)
docker exec <TEN_CONTAINER_N8N> npm cache verify
docker exec <TEN_CONTAINER_N8N> npm cache clean --force
docker restart <TEN_CONTAINER_N8N>
```

* Cài lại `n8n-nodes-ultimate` bằng đúng phương thức ban đầu rồi restart n8n một lần nữa.
* Không xóa toàn bộ `/home/node/.n8n`, không chép file thủ công vào `node_modules` và không tạo package directory khi n8n đang chạy. Trong lúc package chưa tải, UI có thể tạm báo node chưa nhận diện; workflow sẽ hoạt động lại sau khi package được nạp thành công.

## 4) `zpw_sek bị thiếu hoặc không đúng`

* Đây là lỗi phiên đăng nhập của **Zalo User** không còn hợp lệ hoặc thiếu thông tin cần thiết.
* Hãy đăng nhập lại tài khoản Zalo bằng QR, sau đó chọn credential/session mới và chạy lại workflow.
* Không cần xóa workflow. Nếu workflow đang dùng credential cũ, hãy cập nhật lại đúng credential vừa đăng nhập.

## 5) `Node does not require credentials`

* Lỗi này hay gặp với node **Zalo User**.
* Thường xảy ra khi bật `Select a custom credential by ID` nhưng để trống ô `Zalo Credentials`.
* Cách xử lý:
  * Chọn đại một `Zalo Credentials` có sẵn, hoặc
  * Tạo tạm một credentials bất kỳ để node cho phép chạy.
* Tài liệu: [Zalo Expression Credentials](/n8n-nodes-ultimate/danh-sach-nut/zalo/auth/expression-credentials.md)

## 6) Phiên đăng nhập không hoạt động

* Vào **Zalo User → Custom Credential → Phiên đăng nhập: Kiểm tra trạng thái** để xem phiên nào đã hết hạn hoặc proxy không khả dụng.
* Với phiên hết hạn, đăng nhập lại bằng QR rồi chọn phiên mới trong node.
* Nếu vừa thay đổi proxy, hãy deactivate và kích hoạt lại workflow/Trigger để tạo connection mới. Connection đang chạy không tự đổi proxy.
* Operation **Phiên đăng nhập: Xem thông tin** chỉ trả dữ liệu hồ sơ an toàn; không cần và cũng không thể dùng nó để xem cookie, IMEI hay user-agent.

## 7) `The Advanced setting from the cookies extension is missing.`

* Lỗi này thường gặp khi dùng **Facebook Business**.
* Hãy kiểm tra lại theo thứ tự sau:
  * Cài extension Chrome **Local Cookies Manager (Codedao12)**.
  * Đảm bảo cookies được lấy đúng từ trang `business.facebook.com`.
  * Trong extension lấy cookies, bật đủ `Advanced` và `User Agent`.
  * Khi tạo `Facebook API Credentials`, nhập đúng `password` theo yêu cầu.
* Sau khi cập nhật credentials, chạy lại node.
* Tài liệu: [Facebook Credentials](/n8n-nodes-ultimate/xac-thuc/facebookuserapi.md)

## Gợi ý chung khi debug

1. Chụp full lỗi trong `Execution` (bao gồm stack nếu có).
2. Kiểm tra version package đang chạy có đúng như docs không.
3. Khi đổi version package, nên restart n8n để làm mới toàn bộ node registry.

Nếu cần gửi báo lỗi, hãy kèm phiên bản n8n, phiên bản package và phần lỗi liên quan đã che thông tin riêng tư; không gửi cookie, token, số điện thoại hoặc dữ liệu workflow.