[Node.Js] npm error code ERR_INVALID_ARG_TYPE 해결하기

개요

---

기존에 Nodejs 18버전을 사용하다가 2025-04-02 기준 lts 버전인 22.14.0 버전으로 버전 업그레이드 후 React 프로젝트를 하려고 했는데 에러가 발생하였다.

스크립트 실행 안됨

rebuild 안됨

0 verbose cli C:\Users\koe73\AppData\Local\nvm\v22.14.0\node.exe C:\Users\koe73\OneDrive\Desktop\cli
1 info using npm@11.2.0
2 info using node@v22.14.0
3 silly config load:file:C:\Users\koe73\OneDrive\Desktop\cli\npmrc
4 silly config load:file:C:\Users\koe73\OneDrive\Desktop\cli\.npmrc
5 silly config load:file:C:\Users\koe73\.npmrc
6 silly config load:file:C:\Users\koe73\AppData\Local\nvm\v22.14.0\etc\npmrc
7 verbose title npm run test
8 verbose argv "run" "test"
9 verbose logfile logs-max:10 dir:C:\Users\koe73\AppData\Local\npm-cache\_logs\2025-04-02T08_42_32_678Z-
10 verbose logfile C:\Users\koe73\AppData\Local\npm-cache\_logs\2025-04-02T08_42_32_678Z-debug-0.log
11 silly logfile start cleaning logs, removing 1 files
12 silly logfile done cleaning log files
13 verbose stack TypeError [ERR_INVALID_ARG_TYPE]: The "file" argument must be of type string. Received undefined
13 verbose stack     at normalizeSpawnArguments (node:child_process:539:3)
13 verbose stack     at spawn (node:child_process:746:13)
13 verbose stack     at promiseSpawn (C:\Users\koe73\OneDrive\Desktop\cli\node_modules\@npmcli\promise-spawn\lib\index.js:39:16)
13 verbose stack     at spawnWithShell (C:\Users\koe73\OneDrive\Desktop\cli\node_modules\@npmcli\promise-spawn\lib\index.js:124:10)
13 verbose stack     at promiseSpawn (C:\Users\koe73\OneDrive\Desktop\cli\node_modules\@npmcli\promise-spawn\lib\index.js:12:12)
13 verbose stack     at runScriptPkg (C:\Users\koe73\OneDrive\Desktop\cli\node_modules\@npmcli\run-script\lib\run-script-pkg.js:79:13)
13 verbose stack     at runScript (C:\Users\koe73\OneDrive\Desktop\cli\node_modules\@npmcli\run-script\lib\run-script.js:9:12)
13 verbose stack     at #run (C:\Users\koe73\OneDrive\Desktop\cli\lib\commands\run-script.js:135:13)
13 verbose stack     at async RunScript.exec (C:\Users\koe73\OneDrive\Desktop\cli\lib\commands\run-script.js:44:7)
13 verbose stack     at async Npm.exec (C:\Users\koe73\OneDrive\Desktop\cli\lib\npm.js:208:9)
14 error code ERR_INVALID_ARG_TYPE
15 error The "file" argument must be of type string. Received undefined
16 verbose cwd C:\Users\koe73\OneDrive\Desktop\cli
17 verbose os Windows_NT 10.0.19045
18 verbose node v22.14.0
19 verbose npm  v11.2.0
20 verbose exit 1
21 verbose code 1
22 error A complete log of this run can be found in: C:\Users\koe73\AppData\Local\npm-cache\_logs\2025-04-02T08_42_32_678Z-debug-0.log

Nodejs 18버전은 이제 지원이 종료되므로 앞으로의 프로젝트를 위해 이 문제를 반드시 해결해야만 했다.

---

에러의 원인

---

결과적으로 밝혀낸 원인은 npm 쉘 스크립트 수행 코드의 버그, 내 노트북의 환경 문제였다.
 
npm이 문제라고 생각하였던 이유는
 

• npx react scripts start를 수행하였을 때 프로젝트가 정상적으로 동작하였다.
• Node.Js를 다운그레이드 했을 경우 정상적으로 npm start가 수행되었다.
• 패키지 매니저로 pnpm을 사용할 경우 pnpm start, pnpm run dev가 모든 버전에서 정상적으로 수행되었다.

위 이유들로 npm이 문제라고 판단하였다.
 
때문에 에러를 해결하기 위해선 npm 명령어를 수행할 시 동작 과정이 어떻게 되는지 이해할 필요가 있었다.

---

"npm start" 명령어 수행 시 동작 과정

---

전체적인 동작 과정은 다음과 같다.
 
1. package.json 읽기
 
React 개발자라면 모두 알겠지만 package.json에는 "scripts"라는 부분이 있다.

"scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

 
여기서 npm start 명령어를 수행하면 npm은 "react-scripts" 라는 프로그램에 "start"라는 명령어를 수행해라 라고 이해한다.
 
2. 프로그램 찾기
 
npm은 react-scripts라는 프로그램을 찾는다.
 
3. 새로운 프로세스 시작
 
npm은 child_process.spawn() 이라는 기능을 사용해서 새로운 프로세스를 시작한다.
 
이 프로세스는 "react-scripts start" 명령을 수행한다.
 
4. 쉘 사용하기
 
명령어를 수행하기 위해선 쉘이 필요하다.
 
정상적인 상황에서는 npm이 적절한 쉘을 찾아서 명령어를 실행한다.
 
윈도우에서는 보통 cmd.exe를 사용한다.
 
위 과정이 순조롭게 이루어지면 프로세스가 문제없이 실행된다.

---

해결 방법

---

명령어 수행 시 쉘을 찾는 과정에서 에러가 발생하였다.
 
문제가 된 코드는 다음 경로에 있다.

[nodejs 경로]/node_modules/@npmcli/promise-spawn/lib/index.js

 
위 코드의 73번 라인에서 에러가 발생하였다.

  let command = opts.shell
  // if shell is set to true, we use a platform default. we can't let the core
  // spawn method decide this for us because we need to know what shell is in use
  // ahead of time so that we can escape arguments properly. we don't need coverage here.
  if (command === true) {
    // istanbul ignore next
    command = process.platform === 'win32' ? process.env.ComSpec : 'sh'
  }

  const options = { ...opts, shell: false }

 
opts.shell의 초기값은 true이다. shell script를 수행하였기 때문이다.
 
그 후 command는 운영체제가 무엇인지 판단한 후, 그에 따른 값이 저장된다.
 
process.env.ComSpec는 windows의 cmd 경로이다.
 
정상적으로 동작한다면 command 변수에는 windows라면 cmd의 경로, 아니라면 sh가 들어간다.
 
이후 shell: false를 줌으로써 쉘을 통해 명령을 수행할 수 있도록 한다.
 
하지만 내 환경에서는 process.env.ComSpec의 값이 undefined였다.
 
때문에 이를 다음과 같이 수정해서 해결했다.

command = process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : 'sh'

 
다음 pull request에서 내용을 확인할 수 있다.
https://github.com/npm/cli/pull/8205

Fix: fallback for missing process.env.ComSpec on Windows by SongMinQQ · Pull Request #8205 · npm/cli

---

마무리

---

생각치도 못한 에러를 생각치도 못한 곳에서 원인을 찾고 해결했다.
 
덕분에 npm의 동작 원리에 대해 알게 되었던것 같다.
 
npm에 pull request를 요청한 상태인데 검토가 잘 될지는 모르겠다.
 
만약 나와 증상이 비슷하고 npm 캐시 삭제, node 재설치, React 프로젝트 재생성과 같은 널리 알려진 방법을 모두 사용해도 안되는 분이 있다면 이 글이 도움이 되었으면 좋겠다.

 

2025-04-03 추가

 

위와 같은 증상일 때 근본적으로 문제를 해결하는 방법은 다음과 같다.

 

cmd나 powershell을 관리자 권한으로 연 후 다음 명령 실행

setx ComSpec "C:\Windows\System32\cmd.exe" /M