개발 에러 사전

npm ERESOLVE 의존성 충돌 해결 — could not resolve dependency

npm 7+ 가 peer dependency 버전 충돌을 엄격히 막아 설치가 중단된 것으로, 충돌 원인을 확인한 뒤 --legacy-peer-deps 또는 버전 정렬로 해결합니다.

npm EACCES 권한 거부 — permission denied (전역 설치)

전역 설치 경로에 쓰기 권한이 없어 발생하며, sudo로 강제하기보다 npm 전역 경로를 사용자 디렉터리로 바꾸거나 nvm을 쓰는 것이 안전합니다.

npm install 에러 해결 총정리

npm install 실패는 대부분 ① package.json 없는 폴더에서 실행(ENOENT) ② node_modules·캐시 손상(EPERM/rename) ③ 사내망·프록시 네트워크 차단(ECONNRESET/ETIMEDOUT) 세 갈래로, 케이스를 먼저 구분한 뒤 그에 맞는 해결을 적용하면 됩니다.

npm run 스크립트 에러 해결 (dev·build·start)

npm run dev·build·start 가 실패하는 원인은 "스크립트 미정의(Missing script)" 와 "스크립트 자체 실패(ELIFECYCLE)" 두 갈래로, 에러 위쪽 실제 메시지부터 읽고 케이스별로 처리하면 됩니다.

EADDRINUSE 포트 이미 사용 중 — listen EADDRINUSE :::3000

같은 포트를 쓰는 프로세스가 이미 떠 있어 서버가 바인딩에 실패한 것으로, 그 프로세스를 종료하거나 다른 포트를 쓰면 됩니다.

CORS policy 차단 — No Access-Control-Allow-Origin

브라우저가 다른 출처(origin)로의 요청을 서버 허용 헤더가 없어 막은 것으로, 해결은 클라이언트가 아니라 서버에서 Access-Control-Allow-Origin 을 보내는 것입니다.

Node ERR_REQUIRE_ESM — ESM 모듈을 require로 불러옴

CommonJS의 require로 ESM 전용 패키지를 불러와 발생하며, dynamic import를 쓰거나 프로젝트를 ESM으로 전환하면 됩니다.

Node.js 설치 안됨·오류 해결 — node 명령어 인식 안됨

Node.js 설치가 끝나도 node.exe 경로가 PATH 에 없거나 nvm 초기화 줄이 셸 설정에 없어서 터미널이 node 를 못 찾는 것으로, OS 별로 PATH 등록 또는 셸 설정을 바로잡으면 해결됩니다.

Next.js Hydration 실패 — text content does not match

서버에서 렌더한 HTML 과 클라이언트 첫 렌더 결과가 달라 발생하며, 렌더 중 브라우저 전용 값(시간·랜덤·localStorage)을 쓰지 않는 것이 핵심입니다.

window is not defined — Next.js 서버 렌더에서 브라우저 객체 접근

서버(Node.js)에는 window·document 가 없는데 렌더·모듈 최상단에서 접근해 발생하며, 브라우저 전용 코드를 useEffect나 ssr:false 안으로 옮기면 됩니다.

Module not found: Can't resolve — 모듈 경로 해석 실패

번들러가 import 한 경로를 찾지 못한 것으로, 패키지 미설치·경로 오타·대소문자 불일치가 3대 원인입니다.

React Too many re-renders — 무한 렌더 루프

렌더 중에 setState 가 호출돼 렌더→상태변경→렌더가 무한 반복되는 것으로, 이벤트 핸들러에 함수를 호출이 아니라 참조로 전달하면 됩니다.

Objects are not valid as a React child — 객체를 직접 렌더

JSX 에 문자열·숫자·엘리먼트가 아닌 객체/배열을 직접 넣어 발생하며, 객체의 특정 필드를 꺼내거나 .map 으로 펼쳐야 합니다.

React Hook 규칙 위반 — Rules of Hooks

훅을 조건문·반복문·일반 함수 안에서 호출해 발생하며, 훅은 컴포넌트/커스텀 훅 최상위에서 항상 같은 순서로 호출해야 합니다.

React key prop 경고 — Each child should have a unique key

리스트 렌더링 시 각 항목에 고유 key를 주지 않아 발생하며, 안정적인 고유 id를 key로 지정하면 됩니다. 배열 인덱스 key는 권장되지 않습니다.

TS2307 Cannot find module — 타입 선언을 찾지 못함

컴파일러가 모듈이나 그 타입 선언을 못 찾은 것으로, 패키지·@types 설치 또는 tsconfig paths 정렬로 해결합니다.

TS2345 인자 타입 불일치 — Argument of type is not assignable

전달한 값의 타입이 함수가 기대하는 타입과 달라 발생하며, 타입을 좁히거나 정의를 맞추는 것이 정석입니다(as 단언은 최후수단).

TS2339 Property does not exist on type — 없는 속성 접근

타입에 정의되지 않은 속성에 접근해 발생하며, 타입 정의를 보강하거나 타입을 좁히는 것이 정석입니다.

TypeScript JSX 플래그 에러 — Cannot use JSX unless the '--jsx' flag is provided

tsconfig에 jsx 설정이 없거나 파일 확장자가 .tsx가 아니어서 발생하며, jsx 옵션 지정과 .tsx 확장자로 해결합니다.

Vercel 빌드 JavaScript heap out of memory — 빌드 메모리 초과

빌드가 Node 의 힙 한도를 넘겨 죽은 것으로, NODE_OPTIONS 로 힙을 늘리거나 빌드 자체를 가볍게 만드는 두 방향으로 해결합니다.

Vercel 배포 Module not found — 로컬은 되는데 배포만 실패(대소문자)

로컬(macOS/Windows)은 대소문자를 구분하지 않아 통과하지만 Vercel(Linux)은 구분해 실패하는 것으로, import 경로 대소문자를 파일명과 정확히 맞추면 됩니다.

Vercel 함수 타임아웃 — FUNCTION_INVOCATION_TIMEOUT

서버리스 함수가 실행 시간 한도를 넘겨 종료된 것으로, 작업을 줄이거나 maxDuration을 늘리거나 백그라운드/스트리밍으로 전환합니다.

git push rejected non-fast-forward — 원격이 앞서 있어 푸시 거부

원격에 내 로컬이 모르는 커밋이 있어 푸시가 거부된 것으로, 먼저 pull(rebase 권장)로 원격 변경을 합친 뒤 푸시합니다.

git refusing to merge unrelated histories — 히스토리 공유 안 됨

서로 공통 조상이 없는 두 히스토리를 합치려 해서 막힌 것으로, 의도가 맞다면 --allow-unrelated-histories 로 1회 허용합니다.

Python ModuleNotFoundError — No module named

파이썬이 import할 모듈을 찾지 못한 것으로, 미설치·가상환경 불일치·import 경로 문제가 원인입니다. 활성화된 환경에 pip로 설치하면 대부분 해결됩니다.

파이썬 설치 오류·설치 안됨 해결

설치 자체가 깨진 게 아니라 OS가 python 실행 파일을 PATH에서 못 찾는 경우가 대부분으로, 윈도우는 PATH 등록·Store 별칭 해제, 맥은 python3/pyenv 사용으로 해결합니다.

Docker 포트 할당 충돌 — port is already allocated

호스트 포트를 이미 다른 컨테이너/프로세스가 점유해 컨테이너가 뜨지 못한 것으로, 점유 컨테이너를 정리하거나 다른 호스트 포트로 매핑합니다.

도커 데스크톱 실행 안됨·설치 안됨 해결

대부분 윈도우의 가상화(VT-x/AMD-V)·WSL2·가상 머신 플랫폼이 꺼져 있어서 도커 엔진이 못 뜨는 것으로, 케이스별로 가상화 켜기 → WSL2 업데이트 → 설정 리셋 순서로 잡습니다.

Vite Failed to resolve import — 모듈 경로 해석 실패

Vite가 import 경로를 찾지 못한 것으로, 미설치·경로 오타·확장자/alias 문제가 원인입니다. dev 서버 재시작이 필요한 경우도 있습니다.