Cách sửa lỗi 'npm ERR! code E401' Unauthorized Registry

Vấn đề

Ít có điều gì làm gián đoạn quy trình làm việc nhanh hơn một lỗi xác thực trong quá trình build production. Lỗi 401 Unauthorized là cách registry thông báo rằng nó không nhận diện được thông tin xác thực của bạn. Có thể client npm của bạn đang gửi một token không hợp lệ, hoặc hoàn toàn không gửi token nào cả.

npm ERR! code E401
npm ERR! 401 Unauthorized - GET https://registry.npmjs.org/@scope/package - You must be logged in to install this package.

Bạn thường sẽ gặp lỗi này khi làm việc với các package có scope riêng tư (private scoped packages), chẳng hạn như @mycompany/internal-tool. Tuy nhiên, lỗi này cũng có thể xảy ra với các package công khai nếu phiên làm việc (session) cục bộ của bạn đã hết hạn hoặc file .npmrc của bạn chứa các thiết lập xung đột.

Bước 1: Xác minh danh tính hiện tại của bạn

Hãy bắt đầu bằng cách kiểm tra xem npm đang nhận diện bạn là ai. Chạy lệnh này trong terminal của bạn:

npm whoami

Nếu terminal trả về lỗi 401 hoặc thông báo "this command requires you to be logged in," phiên làm việc của bạn đã kết thúc. Nếu nó trả về sai username, có khả năng bạn đang đăng nhập vào tài khoản cá nhân thay vì tài khoản công ty. Đây là một sai sót phổ biến khi các lập trình viên phải xử lý nhiều dự án cùng lúc.

Bước 2: Làm mới phiên làm việc của bạn

Cách khắc phục đáng tin cậy nhất là thực hiện lại quy trình đăng nhập. Quá trình này sẽ xóa bỏ token cũ và ghi một token mới vào cấu hình global của bạn. Nhiều loại token tự động hết hạn sau 30 ngày không hoạt động, vì vậy việc làm mới nhanh chóng thường sẽ giải quyết được vấn đề.

npm logout
npm login

Lưu ý rằng nếu bạn đang sử dụng một registry của bên thứ ba như GitHub Packages hoặc Artifactory, bạn phải bao gồm flag registry. Ví dụ, GitHub yêu cầu:

npm login --registry=https://npm.pkg.github.com

Bước 3: Kiểm tra cấu hình .npmrc của bạn

Nếu việc đăng nhập thất bại, các file cấu hình của bạn có khả năng đang bị xung đột. npm tìm kiếm các file .npmrc ở hai vị trí chính: thư mục home và thư mục gốc của dự án. Các thiết lập ở cấp độ dự án luôn có mức ưu tiên cao hơn.

File .npmrc Global

Trên macOS hoặc Linux, bạn có thể tìm thấy file này tại ~/.npmrc. Người dùng Windows sẽ tìm thấy tại C:\Users\<Username>\.npmrc. Hãy mở file và tìm các dòng tương tự như sau:

//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx

Kiểm tra xem có các dòng bị trùng lặp hay không. Nếu bạn có ba token khác nhau cho cùng một registry, npm có thể đang gửi sai token. Đối với các scoped package, hãy đảm bảo việc ánh xạ (mapping) được thực hiện rõ ràng:

@mycompany:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=your-36-character-token

File .npmrc cấp dự án

Kiểm tra thư mục gốc của dự án để tìm file .npmrc cục bộ. Nếu file này trỏ đến một registry cụ thể nhưng thiếu auth token, npm sẽ bỏ qua thông tin xác thực global của bạn. Điều này dẫn đến lỗi 401 ngay cả khi bạn đã đăng nhập ở cấp độ global.

Bước 4: Khắc phục lỗi CI/CD và tự động hóa

Các môi trường tự động hóa như GitHub Actions hoặc GitLab CI không thể xử lý việc đăng nhập tương tác. Bạn phải sử dụng các biến môi trường (environment variables). Một sai lầm phổ biến là code cứng (hardcode) một token mà cuối cùng nó sẽ hết hạn.

Đảm bảo file .npmrc của dự án được cấu hình để đọc dữ liệu từ môi trường một cách linh hoạt:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Xác minh rằng NPM_TOKEN đã được định nghĩa trong các secret của CI. Nếu biến này bị thiếu hoặc trống, npm sẽ gửi nguyên văn chuỗi "${NPM_TOKEN}" đến server. Registry sẽ ngay lập tức từ chối yêu cầu này với lỗi 401.

Bước 5: Xóa Cache và cài đặt lại

Đôi khi npm lưu giữ trạng thái chưa được xác thực trong bộ nhớ cache metadata cục bộ. Nếu thông tin xác thực của bạn chính xác nhưng lỗi vẫn còn, đã đến lúc dọn dẹp mọi thứ. Hãy ép buộc xóa cache để loại bỏ bất kỳ header cũ nào:

npm cache clean --force

Sau đó, hãy xóa các file artifact cục bộ để đảm bảo một khởi đầu sạch sẽ:

rm -rf node_modules package-lock.json
npm install

Cách xác minh việc khắc phục

Chạy ba bước kiểm tra sau để xác nhận thiết lập của bạn đã ổn định:

Kiểm tra danh tính: npm whoami sẽ trả về username của bạn ngay lập tức.
Kiểm tra Metadata: Thử lệnh npm view @scope/package-name. Nếu bạn thấy một đối tượng JSON với các số phiên bản, việc xác thực của bạn đã thành công.
Cài đặt: Chạy npm install. Nếu CLI vượt qua giai đoạn "idealTree", quá trình bắt tay (handshake) đã hoàn tất.

Mẹo khắc phục sự cố

Xác thực hai yếu tố (2FA): Đảm bảo npm CLI của bạn là phiên bản 9 trở lên. Các phiên bản cũ hơn thường không kích hoạt được lời nhắc 2FA, dẫn đến các lỗi 401 không thông báo.
Proxy doanh nghiệp: Nếu bạn đang ở sau tường lửa, các thiết lập proxy trong npm config list có thể đang loại bỏ header Authorization. Hãy kiểm tra với đội ngũ hạ tầng mạng của bạn.
Scope của Token: Khi tạo token thủ công, hãy đảm bảo nó có quyền "Read". Một token bị giới hạn ở quyền "Publish only" sẽ thất bại khi thực hiện lệnh npm install thông thường.