Tunneling socket could not be established: Sửa lỗi Node.js và npm
Tunneling socket could not be established là thông báo lỗi trong Node.js khi chương trình cố mở đường hầm qua proxy để kết nối tới địa chỉ HTTPS nhưng thất bại. Lỗi hay gặp khi chạy npm install, khi tiện ích VS Code tải dữ liệu, khi công cụ như Cypress, Electron tải tệp cài đặt, hoặc trong mã dùng thư viện HTTP qua proxy. Phần đuôi thông báo như statusCode=407, cause=connect ECONNREFUSED hay cause=socket hang up cho biết nguyên nhân cụ thể. Bài này ProxyVN giải thích cơ chế đường hầm, cách đọc từng biến thể lỗi và thứ tự kiểm tra để sửa nhanh. Xem thêm dịch vụ tại ProxyVN.
Tổng quan về lỗi tunneling socket could not be established
Khi một chương trình Node.js cần gọi địa chỉ HTTPS qua proxy HTTP, nó không gửi yêu cầu thẳng cho proxy mà yêu cầu proxy mở đường hầm bằng lệnh CONNECT. Proxy kết nối tới máy chủ đích, trả lời "200 Connection Established", sau đó chương trình bắt tay TLS với máy chủ đích qua đường hầm đó. Nếu bất kỳ bước nào thất bại, thư viện tạo đường hầm báo lỗi "tunneling socket could not be established" kèm nguyên nhân.
Thông báo này xuất phát từ các thư viện tạo đường hầm phổ biến trong hệ sinh thái Node.js, đặc biệt là những thư viện dùng trong các công cụ đời cũ. Công cụ đời mới có thể báo lỗi với câu chữ khác, nhưng nguyên nhân và cách sửa tương tự.
Lỗi tunneling socket could not be established xuất hiện ở đâu
- npm, yarn, pnpm: khi cài gói từ registry qua proxy công ty hay proxy mua.
- VS Code: khi tải tiện ích, cập nhật, hay tiện ích gọi API bên ngoài.
- Công cụ cài đặt tải tệp nhị phân: Cypress, Puppeteer, Electron, các gói có bước tải tệp sau khi cài.
- Mã ứng dụng: dùng thư viện HTTP qua proxy với cấu hình đường hầm.
- Hệ thống CI: máy chủ build nằm sau proxy doanh nghiệp.
Cấu trúc thông báo lỗi
Thông báo đầy đủ thường có dạng "tunneling socket could not be established, statusCode=407" hoặc "tunneling socket could not be established, cause=connect ECONNREFUSED 127.0.0.1:8080". Phần sau dấu phẩy là manh mối quan trọng nhất, quyết định hướng sửa.
Cơ chế đường hầm gây ra lỗi tunneling socket could not be established
Hiểu đường hầm hoạt động ra sao giúp biết lỗi nằm ở chặng nào.
Đường hầm CONNECT qua proxy
Chặng 1: Kết nối tới proxy
Chương trình mở kết nối TCP tới địa chỉ và cổng của proxy. Nếu proxy không chạy, sai cổng, tường lửa chặn, lỗi xuất hiện ở đây với nguyên nhân ECONNREFUSED, ETIMEDOUT hay ENOTFOUND.
Chặng 2: Gửi lệnh CONNECT
Chương trình gửi "CONNECT tenmien:443 HTTP/1.1" kèm tiêu đề xác thực nếu có. Proxy kiểm tra quyền, nếu từ chối trả mã 407 hay 403. Thư viện báo lỗi kèm statusCode.
Chặng 3: Proxy kết nối tới đích
Proxy mở kết nối tới máy chủ đích. Nếu đích không tới được hoặc proxy chặn tên miền, proxy trả mã lỗi như 502, 503 hay đóng kết nối, thư viện báo socket hang up hay statusCode tương ứng.
Chặng 4: Bắt tay TLS qua đường hầm
Sau khi đường hầm mở, chương trình bắt tay TLS với máy chủ đích. Lỗi ở chặng này thường hiện thành lỗi chứng chỉ như "self signed certificate in certificate chain" hơn là lỗi đường hầm. Cơ chế đường hầm CONNECT được giải thích trong bài proxy tunnel là gì.
Đọc các biến thể của lỗi tunneling socket could not be established
Bảng dưới gom các biến thể hay gặp và nguyên nhân tương ứng.
Các biến thể thông báo lỗi
Phần đuôi thông báo |
Nguyên nhân khả dĩ |
Hướng sửa |
|---|---|---|
statusCode=407 |
Proxy yêu cầu xác thực, thiếu hoặc sai tài khoản |
Thêm user:pass vào URL proxy, mã hoá ký tự đặc biệt |
statusCode=403 |
Proxy từ chối tên miền hoặc cổng |
Kiểm tra chính sách proxy, danh sách cho phép |
statusCode=502, 503 |
Proxy không kết nối được tới đích |
Kiểm tra đích còn sống, proxy có ra Internet không |
cause=connect ECONNREFUSED |
Không có gì nghe ở địa chỉ proxy |
Kiểm tra proxy đang chạy, đúng cổng |
cause=connect ETIMEDOUT |
Tường lửa chặn hoặc proxy quá chậm |
Kiểm tra mạng, tường lửa, đổi proxy |
cause=getaddrinfo ENOTFOUND |
Không phân giải được tên máy chủ proxy |
Sửa tên máy chủ proxy, kiểm tra DNS |
cause=socket hang up |
Proxy đóng kết nối giữa chừng |
Sai giao thức, proxy quá tải, proxy chặn |
cause=write EPROTO, wrong version number |
Khai báo https:// cho proxy HTTP thường |
Đổi URL proxy thành http:// |
statusCode=407
Đây là biến thể phổ biến nhất với proxy mua và proxy công ty. Proxy cần tài khoản mà chương trình không gửi, gửi sai, hoặc ký tự đặc biệt trong mật khẩu làm hỏng URL. Cơ chế mã 407 có trong bài sửa lỗi 407 Proxy Authentication Required.
cause=connect ECONNREFUSED 127.0.0.1
Proxy trỏ về máy cục bộ nhưng không có chương trình nào nghe ở cổng đó. Thường do biến môi trường hay cấu hình npm còn sót từ một phần mềm proxy đã tắt hoặc gỡ. Tình huống được giải thích trong bài proxy 127.0.0.1.
cause=socket hang up
Proxy chấp nhận kết nối rồi đóng ngay. Nguyên nhân hay gặp là gửi TLS tới proxy chỉ nói HTTP, proxy SOCKS bị khai báo như proxy HTTP, proxy quá tải hoặc chặn kết nối CONNECT tới cổng không phải 443.
wrong version number
Khi URL proxy viết là https://host:port trong khi proxy là proxy HTTP thường, chương trình mở TLS tới proxy và nhận dữ liệu HTTP, báo lỗi phiên bản. Đây là lỗi rất phổ biến do nhầm giữa "proxy cho HTTPS" và "proxy nói HTTPS".
Nơi cấu hình proxy cho Node.js và npm
Lỗi thường đến từ một cấu hình bị quên ở đâu đó. Biết các nơi có thể chứa cấu hình proxy giúp dọn sạch nhanh.
Nơi cấu hình proxy cho Node và npm
Biến môi trường
HTTP_PROXY, HTTPS_PROXY, NO_PROXY, cả chữ hoa và chữ thường. npm, nhiều thư viện và công cụ đọc các biến này. Trên Windows, xem trong System Properties, Environment Variables, cả biến người dùng và biến hệ thống. Trên macOS, Linux, xem tệp cấu hình shell như .bashrc, .zshrc. Kiểm tra nhanh bằng lệnh set (Windows) hoặc env | grep -i proxy.
Tệp .npmrc
npm có các khoá proxy, https-proxy, noproxy, strict-ssl, cafile trong tệp .npmrc. Có .npmrc ở thư mục người dùng, ở thư mục dự án và ở cấp toàn cục. Lệnh npm config list hiện cấu hình đang có hiệu lực, npm config get https-proxy cho biết giá trị cụ thể. Tài liệu các khoá có ở trang config của npm. Hướng dẫn chi tiết có trong bài npm proxy.
Cài đặt của VS Code
VS Code có khoá http.proxy, http.proxyStrictSSL, http.proxySupport trong settings.json. Tiện ích chạy trong VS Code thường dùng cấu hình này. Cấu hình đầy đủ có trong bài VS Code proxy.
Cấu hình riêng của từng công cụ
Yarn có .yarnrc hoặc .yarnrc.yml, pnpm đọc .npmrc, Cypress đọc biến môi trường riêng, Git có cấu hình http.proxy riêng. Một dự án có thể vướng nhiều nơi cùng lúc. Cấu hình proxy cho Git có trong bài Git proxy.
Thứ tự ưu tiên
Thông thường cấu hình dòng lệnh đè cấu hình tệp dự án, tệp dự án đè tệp người dùng, tệp người dùng đè biến môi trường. Thứ tự cụ thể khác nhau giữa công cụ. Khi sửa mà không có tác dụng, khả năng cao còn một cấu hình ưu tiên cao hơn đang đè lên.
Thứ tự kiểm tra khi gặp lỗi tunneling socket could not be established
Làm theo thứ tự này giúp tránh sửa mò.
Bước 1: Xác định có đang cần proxy không
Nếu mạng của anh em ra Internet trực tiếp được, không cần proxy, lỗi có thể chỉ do cấu hình proxy cũ còn sót. Xoá cấu hình proxy rồi thử lại là đủ. Nếu mạng bắt buộc qua proxy như mạng công ty, chuyển sang bước 2.
Bước 2: Xem cấu hình đang có hiệu lực
Chạy npm config list và in biến môi trường proxy. Ghi lại tất cả giá trị proxy đang có. Thường sẽ thấy ngay một giá trị lạ như 127.0.0.1:8888 của công cụ gỡ lỗi đã tắt.
Bước 3: Thử proxy độc lập
Chạy curl -v -x http://host:port https://registry.npmjs.org để thử proxy ngoài Node.js. Nếu curl cũng lỗi, proxy hoặc mạng có vấn đề. Nếu curl chạy, vấn đề nằm ở cấu hình của Node.js hay npm. Các lệnh curl hữu ích có trong bài cURL proxy là gì.
Bước 4: Kiểm tra giao thức trong URL proxy
URL proxy gần như luôn bắt đầu bằng http://, kể cả khi đặt cho khoá https-proxy hay biến HTTPS_PROXY. Đổi https:// thành http:// nếu proxy là proxy HTTP thường.
Bước 5: Kiểm tra xác thực
Thêm tài khoản vào URL theo dạng http://user:matkhau@host:port. Ký tự đặc biệt trong mật khẩu như @, :, #, % phải mã hoá URL, ví dụ @ thành %40. Định dạng proxy đúng chuẩn có trong bài định dạng proxy.
Bước 6: Kiểm tra danh sách không dùng proxy
Registry nội bộ, máy chủ trong mạng công ty cần đi thẳng. Thêm vào NO_PROXY hoặc khoá noproxy của npm. Cách viết danh sách có trong bài NO_PROXY là gì.
Bước 7: Kiểm tra chứng chỉ của proxy công ty
Nếu đường hầm mở được nhưng gặp lỗi chứng chỉ, proxy công ty đang giải mã HTTPS. Xem phần chứng chỉ ở dưới.
Xử lý chứng chỉ khi gặp lỗi tunneling socket could not be established
Proxy công ty giải mã HTTPS đưa ra chứng chỉ do công ty ký. Node.js dùng kho chứng chỉ riêng nên không tin chứng chỉ đó.
Chứng chỉ của proxy công ty
Thêm chứng chỉ gốc của công ty
Lấy tệp chứng chỉ gốc từ bộ phận IT, đặt biến môi trường NODE_EXTRA_CA_CERTS trỏ tới tệp đó. Node.js sẽ tin thêm chứng chỉ này bên cạnh kho mặc định. Với npm, có thể dùng khoá cafile trong .npmrc.
Không tắt kiểm tra chứng chỉ
Đặt strict-ssl=false cho npm hay NODE_TLS_REJECT_UNAUTHORIZED=0 cho Node.js tắt kiểm tra chứng chỉ, mở đường cho tấn công trung gian. Chỉ dùng tạm khi gỡ lỗi, không để trong cấu hình lâu dài, không bao giờ dùng trên máy chủ chạy thật.
Chứng chỉ trong Docker và CI
Container và máy chủ CI không có sẵn chứng chỉ công ty. Thêm chứng chỉ vào image và đặt NODE_EXTRA_CA_CERTS trong cấu hình build. Cấu hình proxy cho Docker có trong bài proxy Docker.
Lỗi tunneling socket could not be established trong mã ứng dụng
Khi tự viết mã gọi API qua proxy, lỗi có thể đến từ cách cấu hình thư viện.
Dùng proxy agent
Node.js không tự dùng proxy cho mô-đun http và https lõi. Cần một agent hỗ trợ proxy, phổ biến là bộ thư viện trong kho proxy-agents với https-proxy-agent cho proxy HTTP, socks-proxy-agent cho SOCKS. Tạo agent với URL proxy rồi truyền vào tuỳ chọn agent của yêu cầu. Cách mô-đun HTTP lõi nhận agent có trong tài liệu http của Node.js.
Axios
Axios có tuỳ chọn proxy riêng, nhưng với HTTPS qua proxy HTTP, nhiều người gặp lỗi vì tuỳ chọn này xử lý không như mong đợi. Cách ổn định là đặt proxy: false và truyền httpsAgent tạo từ https-proxy-agent. Tuỳ chọn cấu hình có ở trang Request Config của Axios. Hướng dẫn chi tiết có trong bài axios proxy.
fetch trong Node.js
fetch có sẵn từ Node.js 18 dựa trên thư viện undici, mặc định không đọc biến HTTP_PROXY. Cần dùng ProxyAgent của undici hoặc thư viện bọc. Các bản Node.js mới đang bổ sung hỗ trợ đọc biến proxy, kiểm tra tài liệu của bản đang dùng.
Thư viện request đời cũ
Thư viện request đã ngừng phát triển nhưng vẫn nằm trong nhiều dự án cũ và là nguồn gốc của thông báo lỗi kinh điển này. Nếu có thể, chuyển sang thư viện hiện đại. Nếu chưa chuyển được, đặt tuỳ chọn proxy đúng định dạng và kiểm tra các biến môi trường mà request tự đọc.
Lỗi tunneling socket could not be established trong VS Code
VS Code là ứng dụng Electron, chạy trên Node.js. Lỗi đường hầm trong VS Code có vài đặc điểm riêng.
Khi tải tiện ích
Chợ tiện ích báo không tải được, cửa sổ Output hiện lỗi đường hầm. VS Code dùng cấu hình http.proxy trong settings.json, nếu trống thì dùng proxy hệ thống hoặc biến môi trường tuỳ thiết lập http.proxySupport. Đặt http.proxy rõ ràng là cách chắc nhất trong mạng công ty.
Tiện ích tự gọi mạng
Một số tiện ích như trình quản lý gói, công cụ AI, công cụ kiểm tra mã tự gửi yêu cầu bằng thư viện riêng, không qua cơ chế proxy của VS Code. Tiện ích đó cần biến môi trường HTTPS_PROXY hoặc cài đặt proxy riêng của nó. Đọc tài liệu tiện ích khi chỉ một tiện ích lỗi còn các phần khác chạy.
Terminal tích hợp
Lệnh npm chạy trong terminal của VS Code dùng biến môi trường và .npmrc như terminal ngoài, không dùng http.proxy của VS Code. Nhiều người đặt proxy trong VS Code rồi thắc mắc vì sao npm vẫn lỗi.
Remote SSH và Dev Containers
Khi làm việc từ xa, máy chủ VS Code chạy trên máy đích, cần proxy của máy đích chứ không phải máy cá nhân. Cấu hình biến proxy trên máy đích hoặc trong cấu hình container.
Lỗi khi cài gói có bước tải tệp nhị phân
Nhiều gói npm tải thêm tệp nhị phân lớn sau khi cài, ví dụ trình duyệt cho công cụ tự động hoá hay khung chạy ứng dụng máy tính. Bước tải này có thể dùng cơ chế proxy khác npm.
Cypress
Cypress tải tệp nhị phân của riêng nó khi cài. Bước này đọc biến HTTPS_PROXY, không đọc khoá proxy trong .npmrc. Đặt biến môi trường trước khi chạy npm install, hoặc tải tệp nhị phân thủ công rồi chỉ đường dẫn qua biến cài đặt của Cypress. Cấu hình proxy khi chạy kiểm thử Cypress có trong bài Cypress proxy.
Puppeteer và Playwright
Puppeteer, Playwright tải trình duyệt sau khi cài. Cả hai đọc biến proxy môi trường. Trong mạng hạn chế, có thể bỏ qua bước tải bằng biến môi trường tương ứng rồi chỉ tới trình duyệt có sẵn. Cách dùng proxy khi chạy Puppeteer có trong bài cách sử dụng proxy trong Puppeteer.
Electron và gói biên dịch sẵn
Gói Electron và các gói có mã biên dịch sẵn tải tệp từ máy chủ riêng hoặc GitHub. Một số cần biến bật proxy riêng, một số cho đổi máy chủ tải sang gương nội bộ. Khi npm install treo ở bước postinstall với lỗi đường hầm, khả năng cao là bước tải tệp nhị phân của một gói như vậy.
Cách khoanh vùng
Chạy npm install với tuỳ chọn ghi log chi tiết, xem lỗi xuất hiện ở bước tải gói từ registry hay ở bước postinstall của gói nào. Mỗi trường hợp cần sửa ở chỗ khác nhau.
Lỗi tunneling socket could not be established với proxy mua
Ngoài proxy công ty, nhiều anh em dùng proxy mua cho công cụ Node.js như bot, công cụ thu thập dữ liệu.
Proxy có mật khẩu
Proxy mua thường xác thực bằng tài khoản. Lỗi 407 là dấu hiệu tài khoản chưa đúng hoặc chưa mã hoá ký tự đặc biệt. Proxy xác thực bằng IP whitelist thì cần thêm IP máy chạy công cụ.
Proxy SOCKS5
Khai báo proxy SOCKS5 vào biến HTTPS_PROXY hay agent HTTP sẽ cho lỗi socket hang up. Dùng socks-proxy-agent với URL socks5://. Hoặc dùng cổng HTTP của cùng proxy. Khác biệt hai loại có trong bài proxy HTTP và SOCKS5.
Proxy xoay đổi IP giữa chừng
Proxy xoay đổi IP khi đường hầm đang mở có thể làm kết nối bị đóng. Với tác vụ dài, chọn chế độ giữ phiên. Với npm install, không nên dùng proxy xoay mà dùng mạng trực tiếp.
Chọn proxy ổn định
Proxy ổn định giảm lỗi đường hầm do proxy quá tải. Nếu cần proxy Việt Nam ổn định cho công cụ Node.js, anh em có thể mua proxy tại ProxyVN, mỗi proxy hỗ trợ cả HTTP và SOCKS5.
Lỗi tunneling socket could not be established trên Windows, WSL và Docker
Môi trường chạy ảnh hưởng nhiều tới việc chương trình nhìn thấy proxy nào.
Windows
Biến môi trường đặt trong System Properties chỉ có hiệu lực với cửa sổ dòng lệnh mở sau khi đặt. Mở lại terminal sau khi đổi biến. Phần mềm proxy trên Windows đặt proxy hệ thống, nhưng Node.js không đọc proxy hệ thống của Windows, chỉ đọc biến môi trường.
WSL
WSL có mạng riêng, proxy 127.0.0.1 của Windows không truy cập được từ WSL ở chế độ NAT. Lỗi ECONNREFUSED 127.0.0.1 trong WSL thường do điều này. Cách cấu hình có trong bài WSL proxy.
Docker
Container không kế thừa biến môi trường của máy chủ. Truyền biến proxy khi build và khi chạy. Proxy chạy trên máy chủ ở 127.0.0.1 không truy cập được từ container, cần dùng địa chỉ đặc biệt trỏ về máy chủ.
Ghi log chi tiết để gỡ lỗi
Với npm, thêm tuỳ chọn --loglevel verbose để thấy từng yêu cầu gửi tới đâu, qua proxy nào. Với mã Node.js, đặt biến NODE_DEBUG cho mô-đun http, https, tls để in thông tin kết nối. Log chi tiết thường chỉ ra ngay chương trình đang dùng proxy nào, có gửi tiêu đề xác thực không, và lỗi xảy ra ở chặng nào trong bốn chặng đã nêu. Nhớ xoá log sau khi gỡ lỗi vì log có thể chứa URL proxy kèm mật khẩu.
Phòng tránh lỗi tunneling socket could not be established
Vài thói quen giúp không gặp lại lỗi này.
Tập trung cấu hình proxy một chỗ
Chọn một nơi chính, ví dụ biến môi trường, và để các công cụ khác đọc từ đó. Tránh cấu hình proxy rải rác trong .npmrc, settings.json, cấu hình Git mà không ghi chép lại.
Dọn cấu hình khi đổi mạng
Laptop mang từ công ty về nhà, cấu hình proxy công ty còn nguyên làm mọi lệnh npm lỗi. Dùng kịch bản nhỏ bật tắt proxy theo mạng.
Ghi lại cấu hình cho cả nhóm
Nhóm làm việc sau proxy công ty nên có tài liệu chuẩn: giá trị proxy, danh sách NO_PROXY, cách cài chứng chỉ. Thành viên mới làm theo, không phải mò.
Không lưu mật khẩu proxy trong kho mã
.npmrc của dự án thường được đưa lên Git. Không đặt mật khẩu proxy ở đó, dùng biến môi trường hoặc .npmrc ở thư mục người dùng.
Câu hỏi thường gặp về lỗi tunneling socket could not be established
Vì sao trình duyệt vào được mà npm báo lỗi
Trình duyệt dùng proxy hệ thống và kho chứng chỉ hệ thống, npm dùng biến môi trường, .npmrc và kho chứng chỉ của Node.js. Hai bên cấu hình độc lập, cần cấu hình riêng cho npm.
Đặt HTTPS_PROXY bằng https:// có đúng không
Thường là sai. Biến HTTPS_PROXY nghĩa là proxy dùng cho địa chỉ HTTPS, giá trị vẫn là http://host:port với proxy HTTP thường. Chỉ dùng https:// khi proxy thật sự nói TLS.
Lỗi chỉ xảy ra trên máy chủ CI
Máy chủ CI có mạng, biến môi trường và chứng chỉ khác máy cá nhân. Kiểm tra biến proxy và chứng chỉ trong cấu hình pipeline.
Có nên chuyển sang registry gương để tránh proxy
Registry gương nội bộ của công ty là giải pháp tốt nếu có sẵn. Thêm nó vào NO_PROXY để đi thẳng, vừa nhanh vừa tránh lỗi đường hầm.
Python có gặp lỗi tương tự không
Có, với câu chữ khác. Thư viện requests báo ProxyError kèm "Tunnel connection failed: 407" hay "Cannot connect to proxy" trong cùng tình huống. Nguyên nhân và cách sửa giống nhau về bản chất, chi tiết có trong bài requests.exceptions.ProxyError. pip cũng có cấu hình proxy riêng, xem bài pip proxy.
Lỗi chỉ xảy ra với một số gói npm
Các gói tải từ registry chính chạy bình thường nhưng một vài gói lỗi, thường là gói có bước tải tệp nhị phân từ máy chủ khác, hoặc gói từ registry riêng cần xác thực. Kiểm tra log để biết gói nào và địa chỉ nào lỗi, rồi xử lý riêng địa chỉ đó.
Tổng kết
Tunneling socket could not be established là lỗi mở đường hầm qua proxy trong Node.js và các công cụ như npm, VS Code. Đọc phần đuôi thông báo để biết nguyên nhân: 407 là xác thực, ECONNREFUSED là proxy không chạy, socket hang up hay wrong version number là sai giao thức. Kiểm tra biến môi trường, .npmrc, URL proxy dạng http://, xác thực, NO_PROXY và chứng chỉ công ty. Cần proxy Việt Nam ổn định cho công cụ Node.js, anh em liên hệ Proxy.vn - Nhà cung cấp dịch vụ proxy chất lượng hàng đầu Việt Nam để được tư vấn.
