🚨 npx create-next-app 실행이 실패하는 상황

터미널에 npx create-next-app@latest my-app을 입력했는데 에러 메시지가 쏟아지면 당황스럽습니다. 특히 처음 개발 환경을 세팅하는 비전공자에게는 영어로 된 에러 로그가 어떤 의미인지 파악하기 어렵습니다. 이 글은 create-next-app 실행 중 자주 발생하는 에러를 유형별로 분류하고, 각각의 원인과 해결 방법을 단계별로 안내합니다.

에러 메시지를 먼저 확인하고, 아래 목차에서 자신의 상황과 가장 비슷한 항목을 찾아 따라가세요. 대부분의 문제는 Node.js 버전, 권한, 네트워크 세 가지 범주 안에서 해결됩니다.

🔍 에러 진단 흐름 한눈에 보기

에러를 만났을 때 아래 순서대로 확인하면 빠르게 원인을 좁힐 수 있습니다.

Node.js가 설치돼 있는가? — node --version 입력 후 버전 번호가 출력되는지 확인합니다.
Node.js 버전이 18 이상인가? — Next.js 14 이상은 Node.js 18.17.0 이상을 요구합니다.
npm 또는 npx가 정상 동작하는가? — npx --version을 입력해 버전이 출력되는지 확인합니다.
인터넷 연결이 정상인가? — npm ping을 실행해 PONG이 돌아오는지 확인합니다.
디스크 공간이 충분한가? — 최소 1GB 이상 여유 공간이 있어야 합니다.

이 다섯 가지를 먼저 점검하면 전체 에러의 약 80%는 원인을 특정할 수 있습니다.

🔑 핵심 용어 정리

용어	의미
EACCES	파일이나 디렉토리에 접근 권한이 없다는 에러 코드
ENOENT	지정한 파일이나 경로가 존재하지 않는다는 에러 코드
npx	npm 패키지를 설치하지 않고 바로 실행해주는 도구
PATH	운영체제가 명령어를 찾는 디렉토리 목록
npm cache	npm이 다운로드한 패키지를 임시 저장해두는 공간
LTS	Long Term Support, 안정적인 장기 지원 버전

🛠️ EACCES 권한 에러 해결

EACCES 에러는 npm이 전역 패키지를 설치하려는 디렉토리에 쓰기 권한이 없을 때 발생합니다. 주로 macOS와 Linux에서 sudo로 Node.js를 설치했거나, 기본 전역 경로가 /usr/local/lib로 잡혀 있을 때 나타납니다.

🍎 macOS/Linux에서 해결하기

npm의 전역 설치 디렉토리를 사용자 홈 폴더 아래로 변경하면 sudo 없이도 패키지를 설치할 수 있습니다.

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

그다음 셸 설정 파일에 PATH를 추가합니다. zsh를 사용한다면 ~/.zshrc, bash라면 ~/.bashrc를 편집하세요.

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

설정을 적용한 뒤 npm config get prefix를 실행하세요. 출력이 /Users/사용자이름/.npm-global이면 정상적으로 변경된 것입니다.

🪟 Windows에서 해결하기

Windows에서는 EACCES보다 EPERM 에러가 나타나는 경우가 많습니다. 원인은 동일하게 권한 문제입니다.

관리자 권한으로 터미널(PowerShell 또는 명령 프롬프트)을 실행합니다.
바탕화면 또는 시작 메뉴에서 터미널 아이콘을 마우스 오른쪽 버튼으로 클릭하고 "관리자 권한으로 실행"을 선택합니다.
관리자 터미널에서 npx create-next-app@latest my-app을 다시 실행합니다.

관리자 권한으로도 안 되면 바이러스 백신이 npm의 파일 쓰기를 차단하고 있을 수 있습니다. 백신의 실시간 보호 기능을 일시적으로 끄고 다시 시도해보세요.

📂 ENOENT 경로 에러 해결

ENOENT는 "Error NO ENTry"의 줄임말로, 파일이나 디렉토리를 찾을 수 없다는 의미입니다. create-next-app에서 이 에러가 나오는 대표적인 원인은 세 가지입니다.

📌 npm 캐시가 손상된 경우

이전에 설치가 중간에 끊기면서 캐시 파일이 깨질 수 있습니다. 캐시를 강제로 정리하면 해결됩니다.

npm cache clean --force

정리 후 npx create-next-app@latest my-app을 다시 실행하세요. 캐시 관련 에러가 사라졌다면 정상 복구된 것입니다.

📌 프로젝트 경로에 한글이나 특수문자가 포함된 경우

프로젝트를 생성할 폴더 경로에 한글, 공백, 특수문자가 포함되면 npm이 경로를 올바르게 인식하지 못할 수 있습니다. 예를 들어 C:\Users\홍길동\바탕화면\내프로젝트같은 경로는 문제가 될 수 있습니다.

# 문제 있는 경로
cd C:\Users\홍길동\바탕 화면\my app

# 안전한 경로
cd C:\dev\my-app

영문으로만 구성된 짧은 경로(예: C:\dev 또는 ~/projects)에서 실행하세요. 경로를 변경한 뒤 에러 없이 프로젝트 파일이 생성되면 정상입니다.

📌 npx 자체가 없다는 에러

npx: command not found가 나오면 npm 버전이 너무 오래됐거나 Node.js 설치가 불완전한 경우입니다. npm 5.2.0 이상이면 npx가 자동으로 포함되므로, Node.js를 최신 LTS로 재설치하는 것이 가장 확실합니다.

node --version
npm --version

npm이 5.2.0 미만이거나 명령어 자체가 인식되지 않으면 Node.js 공식 사이트에서 LTS 버전을 다시 설치하세요.

🌐 네트워크 관련 에러 해결

create-next-app은 패키지를 npm 레지스트리에서 다운로드하므로 인터넷 연결이 필수입니다. 네트워크 에러는 ETIMEDOUT, ECONNREFUSED, EAI_AGAIN 같은 코드로 나타납니다.

📌 프록시 또는 VPN 환경

회사나 학교 네트워크에서 프록시를 사용하는 경우 npm에 프록시 설정을 추가해야 합니다.

npm config set proxy http://프록시주소:포트
npm config set https-proxy http://프록시주소:포트

VPN을 사용 중이라면 일시적으로 VPN을 끄고 다시 시도해보세요. 프록시 설정이 맞는데도 실패하면 네트워크 관리자에게 registry.npmjs.org 도메인이 허용 목록에 있는지 확인하세요.

📌 npm 레지스트리 변경

기본 레지스트리가 변경돼 있으면 패키지를 찾지 못할 수 있습니다. 현재 레지스트리를 확인하고 기본값으로 되돌리세요.

npm config get registry
# https://registry.npmjs.org/ 가 아니라면 아래 명령으로 복원
npm config set registry https://registry.npmjs.org/

레지스트리 복원 후 npm ping을 실행해서 응답이 돌아오면 연결이 정상입니다.

📌 DNS 문제

EAI_AGAIN 에러는 DNS 조회가 실패했다는 의미입니다. DNS를 Google Public DNS(8.8.8.8) 또는 Cloudflare DNS(1.1.1.1)로 변경해보세요.

Windows: 네트워크 설정 → 어댑터 속성 → IPv4 → DNS 서버를 8.8.8.8, 8.8.4.4로 변경
macOS: 시스템 설정 → 네트워크 → Wi-Fi → 세부사항 → DNS 탭에서 8.8.8.8 추가

DNS를 변경한 뒤 터미널을 새로 열고 다시 시도하세요.

📦 Node.js 버전 관련 에러 해결

Next.js는 버전마다 요구하는 최소 Node.js 버전이 다릅니다. 버전이 맞지 않으면 설치 도중 호환성 에러가 발생합니다.

Next.js 버전	최소 Node.js 버전
Next.js 13	16.14.0
Next.js 14	18.17.0
Next.js 15	18.18.0

현재 Node.js 버전을 확인하세요.

node --version

출력된 버전이 v16이나 v17이라면 Node.js를 업데이트해야 합니다. 가장 간단한 방법은 Node.js 공식 사이트에서 최신 LTS를 다시 설치하는 것입니다. 기존 버전을 삭제하지 않아도 덮어쓰기로 설치됩니다.

nvm(Node Version Manager)을 사용하고 있다면 아래 명령으로 전환할 수 있습니다.

nvm install --lts
nvm use --lts
node --version

버전 번호가 18.17.0 이상으로 표시되면 create-next-app을 다시 실행하세요.

🔧 PATH 환경변수 문제 해결

Node.js를 설치했는데도 node, npm, npx 명령어가 인식되지 않으면 PATH 설정에 문제가 있는 것입니다.

🪟 Windows PATH 확인

Windows 검색에서 "환경 변수"를 검색하고 "시스템 환경 변수 편집"을 엽니다.
"환경 변수" 버튼을 클릭합니다.
"사용자 변수" 또는 "시스템 변수"에서 Path를 찾아 더블 클릭합니다.
목록에 Node.js 설치 경로(기본값: C:\Program Files\nodejs\)가 있는지 확인합니다.
없으면 "새로 만들기"를 클릭하고 C:\Program Files\nodejs\를 추가합니다.

변경 후 터미널을 완전히 닫고 새로 열어야 적용됩니다.

🍎 macOS PATH 확인

echo $PATH
which node

which node의 출력이 비어 있으면 PATH에 Node.js 경로가 없는 것입니다. nvm을 사용한다면 셸 설정 파일에 nvm 초기화 코드가 있는지 확인하세요.

# ~/.zshrc 에 아래 내용이 있어야 합니다
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

설정을 추가한 뒤 source ~/.zshrc를 실행하고, node --version이 정상 출력되면 해결된 것입니다.

✅ 에러 해결 후 점검 목록

모든 에러를 해결한 뒤 아래 항목을 순서대로 확인하세요.

node --version — v18.17.0 이상 출력
npm --version — 9.0.0 이상 출력
npx --version — 버전 번호 출력
npm ping — PONG 응답
npx create-next-app@latest my-test-app — 프로젝트 생성 성공
cd my-test-app && npm run dev — localhost:3000 접속 가능

모든 항목이 정상이면 개발 환경이 올바르게 구성된 것입니다.

🔄 그래도 안 될 때 시도할 방법

위의 모든 방법을 시도했는데도 에러가 계속 발생한다면 아래 순서로 진행하세요.

Node.js 완전 삭제 후 재설치: 기존 Node.js를 완전히 삭제하고 공식 사이트에서 최신 LTS를 새로 설치합니다.
npm 캐시 전체 삭제: npm cache clean --force 실행 후 %AppData%\npm-cache(Windows) 또는 ~/.npm(macOS) 폴더를 수동으로 삭제합니다.
다른 패키지 매니저 사용: npx 대신 pnpm이나 yarn으로 프로젝트를 생성할 수 있습니다.

# pnpm 사용
pnpm create next-app my-app

# yarn 사용
yarn create next-app my-app

OS 업데이트 확인: Windows 10 이전 버전이나 macOS 11 이하에서는 최신 Node.js가 동작하지 않을 수 있습니다.

패키지 매니저를 바꿔서 성공했다면, 이후 프로젝트에서도 해당 패키지 매니저를 일관되게 사용하세요.

🪤 자주 하는 실수와 예방

실수	예방법
`sudo npx create-next-app`으로 실행	권한 문제가 연쇄적으로 발생합니다. npm 전역 경로를 사용자 디렉토리로 변경하세요
한글 경로에서 프로젝트 생성	영문 경로(예: `C:\dev`)를 사용하세요
여러 Node.js 버전이 충돌	nvm으로 버전을 관리하고, 프로젝트마다 `.nvmrc` 파일을 만드세요
에러 메시지를 읽지 않고 재실행	에러 로그의 첫 번째 `ERR!` 줄이 핵심 원인입니다. 해당 코드를 검색하세요
오래된 터미널 세션 사용	PATH나 환경변수 변경 후에는 반드시 터미널을 새로 열어야 합니다

⚡ VibeStart로 환경 세팅 한 번에 끝내기

Node.js 설치부터 PATH 설정까지 직접 하나하나 확인하기 번거롭다면 VibeStart를 사용해보세요. 운영체제에 맞는 설치 명령어를 단계별로 안내하므로, 환경 세팅에서 발생하는 대부분의 에러를 사전에 방지할 수 있습니다.

⚠️ 면책조항: 이 글의 내용은 2026년 4월 기준으로 작성되었습니다. Node.js, npm, Next.js의 버전 업데이트에 따라 에러 메시지나 해결 방법이 달라질 수 있습니다. 문제가 지속되면 각 도구의 공식 문서를 참고하세요.

❓ 자주 묻는 질문

Q. npx create-next-app 대신 npm create-next-app을 써도 되나요?

npm create next-app도 동일한 동작을 합니다. npm 7 이상에서는 npm create가 npm init의 별칭으로 동작하며, 내부적으로 create-next-app 패키지를 실행합니다.

Q. create-next-app 실행 중 "TypeScript를 사용하시겠습니까?" 같은 질문이 안 나오고 바로 에러가 납니다.

패키지 다운로드 단계에서 실패한 것입니다. 네트워크 연결을 확인하고, npm cache clean --force를 실행한 뒤 다시 시도하세요.

Q. EACCES 에러에서 sudo를 쓰면 안 되나요?

sudo로 실행하면 당장은 해결되지만, 생성된 파일의 소유자가 root로 설정됩니다. 이후 일반 사용자로 해당 파일을 수정하거나 패키지를 추가할 때 다시 권한 에러가 발생합니다. npm 전역 디렉토리를 사용자 폴더로 변경하는 방법이 근본적인 해결입니다.

Q. Windows에서 PowerShell과 명령 프롬프트 중 어떤 것을 써야 하나요?

둘 다 사용 가능합니다. 다만 PowerShell이 더 최신이고 기능이 많으므로 PowerShell을 권장합니다. Windows 11에서는 기본 터미널이 Windows Terminal이며, PowerShell 탭이 기본으로 열립니다.

Q. create-next-app 실행 시 "ERR! code E404" 에러가 나옵니다.

npm 레지스트리에서 패키지를 찾지 못했다는 의미입니다. npm config get registry로 레지스트리 URL을 확인하고, https://registry.npmjs.org/가 아니면 기본값으로 복원하세요.

Q. Node.js를 여러 버전 설치해도 괜찮나요?

nvm을 사용하면 여러 버전을 설치하고 프로젝트마다 전환할 수 있습니다. 단, nvm 없이 Node.js를 여러 번 설치하면 PATH가 꼬일 수 있으므로 반드시 nvm을 통해 관리하세요.

Q. create-next-app 실행이 중간에 멈추면 어떻게 하나요?

Ctrl+C로 강제 종료한 뒤, 생성 중이던 폴더를 삭제하고 다시 실행하세요. 폴더가 남아 있으면 "이미 존재하는 디렉토리" 에러가 발생할 수 있습니다.

Q. --use-pnpm 같은 옵션을 추가하면 에러가 나는데 왜 그런가요?

해당 패키지 매니저가 시스템에 설치되어 있어야 합니다. --use-pnpm을 쓰려면 먼저 npm install -g pnpm으로 pnpm을 설치하세요. 설치 후 터미널을 새로 열고 다시 시도하면 됩니다.

Q. macOS에서 Homebrew로 설치한 Node.js와 공식 설치 파일이 충돌하나요?

충돌할 수 있습니다. 한 가지 방법으로만 설치하는 것이 좋습니다. 이미 둘 다 설치됐다면 which node로 어느 Node.js가 사용되고 있는지 확인하고, 사용하지 않는 쪽을 삭제하세요.

npx create-next-app 에러 해결 총정리: EACCES, ENOENT, 네트워크 오류까지 (2026)