Sửa lỗi 'ERR_INVALID_ARG_TYPE: Đối số "path" phải thuộc kiểu string' trong Node.js

Thông điệp lỗiKhi làm việc với hệ thống tệp hoặc xử lý đường dẫn trong Node.js, bạn có thể gặp phải lỗi crash như sau:

TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received type undefined
    at validateString (internal/validators.js:120:11)
    at Object.join (path.js:375:7)
    at /home/user/project/server.js:15:24

Tại sao lỗi này xảy raNode.js rất nghiêm ngặt về các đối số được truyền vào các module lõi của nó, đặc biệt là fs (File System) và path. Lỗi này xảy ra vì bạn đang gọi một hàm yêu cầu đường dẫn tệp dưới dạng chuỗi (string), nhưng bạn lại truyền vào undefined instead.

Trong hầu hết các trường hợp thực tế, đây không phải là lỗi của chính Node.js, mà là lỗi logic trong cách bạn lấy hoặc xây dựng biến đường dẫn đó. Nếu biến bạn truyền vào fs.readFile() hoặc path.join() không được khởi tạo chính xác, Node sẽ ném ra ngoại lệ ERR_INVALID_ARG_TYPE cụ thể này để ngăn chặn các hành vi không lường trước được.

Các tình huống thường gặp và cách khắc phục### 1. Thiếu biến môi trườngĐây là nguyên nhân phổ biến nhất. Bạn có thể đang cố gắng đọc một đường dẫn từ tệp .env chưa được tải hoặc thiếu một key cụ thể.

// ❌ Lỗi tiềm ẩn
const fs = require('fs');
const data = fs.readFileSync(process.env.CONFIG_PATH); 
// Nếu CONFIG_PATH không có trong .env, nó sẽ trả về undefined

Cách khắc phục: Luôn đảm bảo dotenv được cấu hình ngay đầu tệp thực thi và cung cấp một giá trị dự phòng (fallback).

require('dotenv').config();
const fs = require('fs');

const configPath = process.env.CONFIG_PATH || './config.default.json';
const data = fs.readFileSync(configPath);

2. Lỗi đánh máy trong tên biến hoặc Destructuring đối tượngĐôi khi bạn có thể đang destructuring một đối tượng và gõ sai tên thuộc tính, dẫn đến việc truyền một biến undefined vào hàm xử lý đường dẫn.

// ❌ Lỗi tiềm ẩn
const settings = { filePath: '/etc/hosts' };
const { file_path } = settings; // Lỗi đánh máy: đáng lẽ phải là filePath

const absolutePath = path.resolve(file_path); // file_path là undefined

Cách khắc phục: Kiểm tra lại quy ước đặt tên biến của bạn. Sử dụng TypeScript có thể giúp phát hiện lỗi này ngay khi biên dịch, nhưng trong JavaScript thuần, một dòng console.log đơn giản trước dòng bị lỗi sẽ là trợ thủ đắc lực nhất.

3. Đối số bị undefined trong path.join()Hàm path.join() rất tuyệt vời để xử lý các dấu phân cách trên nhiều nền tảng khác nhau, nhưng nếu bất kỳ đối số nào truyền vào không phải là chuỗi, nó sẽ gặp lỗi.

// ❌ Lỗi tiềm ẩn
const dir = './uploads';
const fileName = getFileName(); // Nếu hàm này trả về null/undefined...

const fullPath = path.join(dir, fileName); // Bị crash tại đây

Cách khắc phục: Kiểm tra tính hợp lệ của dữ liệu đầu vào trước khi nối chúng.

const dir = './uploads';
const fileName = getFileName();

if (!fileName) {
    throw new Error('Filename could not be determined');
}

const fullPath = path.join(dir, fileName);

Quy trình gỡ lỗi từng bướcNếu bạn đang nhìn vào lỗi này mà không biết nó bắt nguồn từ đâu, hãy làm theo các bước sau:

• Kiểm tra Stack Trace: Xem số dòng trong mã nguồn được đề cập trong nhật ký lỗi. Nó thường trỏ đến một lệnh gọi path.join, path.resolve, fs.readFile hoặc fs.writeFile.- Log dữ liệu đầu vào: Ngay trước dòng bị crash, hãy thêm console.log('Path input:', yourVariable, typeof yourVariable);.- Truy tìm nguồn gốc: Nếu nó là undefined, hãy kiểm tra ngược lại. Biến yourVariable được gán ở đâu? Nó có đến từ kết quả trả về của một hàm? Một truy vấn cơ sở dữ liệu? Hay một yêu cầu API?- Triển khai một Guard Clause: Đừng để code tiếp tục chạy nếu đường dẫn không hợp lệ.## Các bước xác minhĐể xác nhận cách khắc phục, bạn có thể chạy một đoạn mã kiểm tra nhỏ để đảm bảo việc xử lý đường dẫn của bạn đã ổn định:

const path = require('path');

function getSafePath(input) {
    if (typeof input !== 'string') {
        console.error('Validation failed: Path must be a string. Received:', typeof input);
        return null;
    }
    return path.resolve(input);
}

// Test 1: Đầu vào hợp lệ
console.log('Test 1:', getSafePath('./test.txt'));

// Test 2: Đầu vào undefined (Nguyên nhân gây lỗi)
console.log('Test 2:', getSafePath(undefined)); 

Nếu ứng dụng của bạn không còn bị crash và bạn thấy logic xử lý lỗi tùy chỉnh hoặc logic dự phòng được kích hoạt, thì việc khắc phục đã thành công.

Mẹo để phòng tránh lỗi- Sử dụng path.resolve() thay vì nối chuỗi: Cách này an toàn hơn và xử lý đường dẫn tuyệt đối so với tương đối tốt hơn.- TypeScript: Nếu có thể, hãy chuyển sang sử dụng TypeScript. Nó sẽ cảnh báo lỗi "Type 'undefined' is not assignable to type 'string'" ngay lập tức khi bạn đang viết mã.- Kiểm tra dữ liệu đầu vào: Sử dụng các thư viện như Joi hoặc Zod để xác thực các đối tượng cấu hình hoặc dữ liệu API trước khi chúng đi đến logic hệ thống tệp.- Giá trị mặc định: Sử dụng toán tử logic OR (||) hoặc toán tử nullish coalescing (??) để cung cấp các giá trị mặc định hợp lý cho các đường dẫn tùy chọn.