개발 에러 사전

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

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

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

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

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으로 전환하면 됩니다.

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로 설치하면 대부분 해결됩니다.

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

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

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

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