프로그래밍
오류 로그에서 진짜 원인 줄을 찾고, 파일 경로와 줄 번호를 읽고, 경고와 실패를 구분하고, 정확한 디버깅 요청을 하기 위한 실전 가이드입니다.
31 개 항목
메시지 구조
First error line
TypeError: Cannot read properties of undefined처음 보이는 명확한 오류 줄은 원인을 찾는 가장 좋은 출발점인 경우가 많습니다.
반복되는 후속 로그보다 먼저, 실패 이름을 직접 말하는 첫 줄을 찾습니다.
TypeError: Cannot read properties of undefined이 로그에서 첫 번째 진짜 오류 줄을 찾아줘.
메시지 구조
Error name
SyntaxError, TypeError, ReferenceError오류 이름은 문제가 어느 종류인지 먼저 알려줍니다.
문법, 실행, 타입, 네트워크, 환경 문제를 구분하는 첫 단서로 사용합니다.
SyntaxError, TypeError, ReferenceError수정 제안 전에 이 오류를 오류 이름 기준으로 분류해줘.
메시지 구조
Error message
Module not found: Can't resolve '@/lib/error-message-guide'오류 문장은 도구가 무엇을 하지 못했는지 설명합니다.
동작과 대상을 읽습니다. 모듈을 못 찾았는지, 속성을 못 읽었는지, 포트를 못 잡았는지 확인합니다.
Module not found: Can't resolve '@/lib/error-message-guide'이 오류 문장을 쉬운 한국어로 풀고 가능한 원인을 짚어줘.
메시지 구조
Stack trace
at SiteHeader (src/components/SiteHeader.tsx:42:15)오류가 발생하기까지 거쳐온 함수 호출 목록입니다.
내 프로젝트 파일을 가리키는 첫 줄을 찾고 그 주변을 확인합니다.
스택 맨 위가 항상 내 코드는 아닙니다. 프레임워크 내부 줄일 수도 있습니다.
at SiteHeader (src/components/SiteHeader.tsx:42:15)이 스택 트레이스에서 내 프로젝트 파일에 해당하는 첫 줄을 찾아줘.
위치 단서
File path
src/components/LanguageSwitcher.tsx파일 경로는 도구가 어떤 파일을 문제와 관련 있다고 보는지 알려줍니다.
의존성 폴더보다 먼저 src, app, components, lib 아래 경로를 봅니다.
src/components/LanguageSwitcher.tsx이 오류에 언급된 프로젝트 파일들을 나열해줘.
위치 단서
Line and column
src/app/page.tsx:27:12줄 번호와 열 번호는 위치를 특정 문자 근처까지 좁혀줍니다.
해당 줄뿐 아니라 위쪽 몇 줄도 함께 봅니다. 실제 원인이 앞에서 시작될 수 있습니다.
src/app/page.tsx:27:12보고된 줄 근처 파일을 보고 무엇이 이상한지 설명해줘.
위치 단서
Project file line
src/lib/git-github.ts:143:7의존성이 아니라 내 소스 코드를 가리키는 스택 또는 빌드 로그 줄입니다.
긴 프레임워크 로그보다 먼저 확인할 줄인 경우가 많습니다.
src/lib/git-github.ts:143:7내 프로젝트 파일 줄과 프레임워크 내부 줄을 나눠줘.
위치 단서
node_modules line
node_modules/next/dist/server/app-render.js설치된 의존성이나 프레임워크 패키지 내부를 가리키는 줄입니다.
패키지 버전이나 설정 문제를 직접 말하지 않는다면 보통 맥락 정보로 봅니다.
일반적인 수정으로 node_modules를 직접 고치면 안 됩니다.
node_modules/next/dist/server/app-render.js이 node_modules 줄이 원인인지 단순 맥락인지 판단해줘.
JavaScript 실행 오류
SyntaxError
SyntaxError: Unexpected token '}'JavaScript 또는 TypeScript가 코드를 문법적으로 해석하지 못했다는 뜻입니다.
보고된 줄 근처의 괄호, 따옴표, 쉼표, JSX 태그, 미완성 표현식을 확인합니다.
SyntaxError: Unexpected token '}'이 줄 주변의 문법 문제를 찾아줘.
JavaScript 실행 오류
TypeError
TypeError: Cannot read properties of undefined실행 중 값이 코드가 기대한 형태나 동작을 가지고 있지 않았다는 뜻입니다.
값이 undefined, null, 객체가 아닌 문자열, 없는 함수일 가능성을 확인합니다.
TypeError: Cannot read properties of undefined이 undefined 값이 어디서 오는지 추적해줘.
JavaScript 실행 오류
ReferenceError
ReferenceError: copy is not defined현재 범위에서 사용할 수 없는 변수나 함수 이름을 사용했다는 뜻입니다.
import, 철자, 범위, 사용 전에 선언됐는지 확인합니다.
ReferenceError: copy is not defined이 이름이 왜 정의되지 않았는지 찾아줘.
JavaScript 실행 오류
Cannot read properties of undefined
Cannot read properties of undefined (reading 'navLabel')undefined인 값에서 속성을 읽으려고 했다는 뜻입니다.
점 앞의 객체를 확인합니다. copy, locale, params, map 조회 결과 등이 원인일 수 있습니다.
Cannot read properties of undefined (reading 'navLabel')이 오류에서 어떤 값이 undefined인지 찾아줘.
JavaScript 실행 오류
is not a function
setOpenMenu is not a function괄호로 호출하려 했지만 해당 값이 함수가 아니라는 뜻입니다.
prop, import, hook 결과, 객체 메서드 이름이 예상과 같은지 확인합니다.
setOpenMenu is not a function이 값이 왜 함수처럼 호출되고 있는지 찾아줘.
Next.js와 웹
Module not found
Module not found: Can't resolve '@/lib/error-message-guide'import에 적힌 파일이나 패키지를 번들러가 찾지 못했다는 뜻입니다.
파일 존재 여부, 경로 철자, alias가 올바른 폴더를 가리키는지 확인합니다.
Module not found: Can't resolve '@/lib/error-message-guide'import 경로와 실제 파일 경로가 맞는지 확인해줘.
Next.js와 웹
Export not found
Export errorMessageGuideCopy doesn't exist in target moduleimport한 이름이 대상 파일에서 export된 이름과 맞지 않는다는 뜻입니다.
import한 이름과 실제 export된 const, function, type 이름을 정확히 비교합니다.
Export errorMessageGuideCopy doesn't exist in target module맞지 않는 import 또는 export 이름을 찾아줘.
Next.js와 웹
Hydration failed
Hydration failed because the server rendered HTML didn't match the client서버가 만든 HTML과 브라우저에서 React가 렌더링한 결과가 다르다는 뜻입니다.
초기 렌더링 중 사용하는 브라우저 전용 값, 날짜, 랜덤 값, localStorage, 테마 상태를 확인합니다.
Hydration failed because the server rendered HTML didn't match the client서버와 클라이언트 렌더링이 달라진 지점을 찾아줘.
Next.js와 웹
404 Not Found
GET /ko/reference/error-message-guide 404요청한 경로나 파일을 찾지 못했다는 뜻입니다.
라우트 폴더, generateStaticParams, 링크 href, 정적 출력 경로를 확인합니다.
GET /ko/reference/error-message-guide 404이 경로가 왜 404를 반환하는지 확인해줘.
Next.js와 웹
500 Internal Server Error
GET /ko 500서버가 요청을 받았지만 처리 중 실패했다는 뜻입니다.
브라우저의 상태 코드만 보지 말고 같은 요청 시점의 터미널 로그를 확인합니다.
GET /ko 500브라우저 500과 그 원인이 된 터미널 오류를 연결해줘.
TypeScript와 lint
Property does not exist on type
Property 'navLabel' does not exist on type 'string'TypeScript가 해당 값의 선언된 타입에 그 속성이 없다고 판단했다는 뜻입니다.
값의 타입이 맞는지, 인덱싱이 맞는지, 데이터 구조가 바뀌었는지 확인합니다.
Property 'navLabel' does not exist on type 'string'TypeScript가 왜 이 속성이 없다고 판단하는지 설명해줘.
TypeScript와 lint
Type is not assignable
Type 'string' is not assignable to type 'Locale'값이 기대 타입과 다른 곳에 전달되고 있다는 뜻입니다.
실제 값 타입과 'to type' 뒤에 나온 기대 타입을 비교합니다.
Type 'string' is not assignable to type 'Locale'이 오류에서 실제 타입과 기대 타입을 나눠서 보여줘.
TypeScript와 lint
ESLint error
React Hook useEffect has a missing dependency정적 검사 규칙이 위험하거나 일관성 없거나 프로젝트 스타일과 맞지 않는 코드를 찾았다는 뜻입니다.
규칙 이름과 파일 줄을 읽고 코드나 의존성 목록을 바꿔야 하는지 판단합니다.
React Hook useEffect has a missing dependency이 lint 오류를 설명하고 동작을 바꾸지 않게 수정해줘.
Next.js와 웹
Build failed
Failed to compile.프로덕션 빌드가 끝까지 완료되지 못했다는 뜻입니다.
요약 문구 위쪽에서 첫 compile, type, lint, route 오류를 찾습니다.
Failed to compile.이 빌드 로그에서 첫 번째로 막는 실패 원인을 찾아줘.
터미널과 시스템
EADDRINUSE
Error: listen EADDRINUSE: address already in use :::3001서버가 사용하려는 포트를 다른 프로세스가 이미 사용 중이라는 뜻입니다.
기존 서버를 끄거나 새 서버를 다른 포트로 실행합니다.
Error: listen EADDRINUSE: address already in use :::3001이 포트를 무엇이 쓰고 있는지 찾고 가장 안전한 다음 단계를 제안해줘.
터미널과 시스템
ENOENT
ENOENT: no such file or directory, open 'next.config.js'프로세스가 해당 경로에 없는 파일이나 폴더를 열려고 했다는 뜻입니다.
현재 작업 경로, 파일명 철자, 확장자, 생성 파일 여부를 확인합니다.
ENOENT: no such file or directory, open 'next.config.js'파일이 없는 것인지 명령이 잘못된 폴더에서 실행된 것인지 확인해줘.
터미널과 시스템
Permission denied
Operation not permitted프로세스가 대상 파일을 읽거나 쓰거나 실행할 권한이 없다는 뜻입니다.
샌드박스 규칙, 파일 권한, 보호 폴더, 승인 필요 여부를 확인합니다.
대상을 이해하지 못한 채 넓은 범위의 권한 변경으로 해결하면 안 됩니다.
Operation not permitted이 권한 오류가 왜 발생했는지와 어떤 승인이 필요한지 설명해줘.
터미널과 시스템
Command not found
zsh: command not found: next셸이 해당 이름의 실행 가능한 명령을 찾지 못했다는 뜻입니다.
의존성 설치 여부, npm script 사용 여부, PATH 설정을 확인합니다.
zsh: command not found: next이 명령 대신 npm script를 실행해야 하는지 알려줘.
디버깅 순서
Warning
DeprecationWarning: module.register() is deprecated경고는 주의가 필요할 수 있다는 뜻이지만, 현재 명령을 반드시 실패시키지는 않습니다.
경고를 실패로 보기 전에 명령이 성공적으로 끝났는지 먼저 확인합니다.
DeprecationWarning: module.register() is deprecated이 출력에서 막는 오류와 막지 않는 경고를 구분해줘.
디버깅 순서
DeprecationWarning
DeprecationWarning: module.register() is deprecated지금은 동작하지만 나중에 교체되거나 제거될 예정이라는 경고입니다.
빌드가 통과한다면 내 코드나 필수 업그레이드를 직접 가리키는 경우가 아니면 후속 점검으로 기록합니다.
DeprecationWarning: module.register() is deprecated이 DeprecationWarning이 배포를 막는지 알려줘.
디버깅 순서
Recent change
The error started after editing SiteHeader.tsx문제가 생기기 직전의 관련 수정은 가장 가치 있는 단서인 경우가 많습니다.
오류 위치와 현재 작업에서 수정된 파일을 비교합니다.
The error started after editing SiteHeader.tsx이 오류를 가장 최근에 변경한 파일들과 비교해줘.
디버깅 순서
Reproduce step
Open /ko, click the language menu, then click the site menu오류를 다시 나타나게 하는 가장 짧은 행동 순서입니다.
명확한 재현 단계가 있어야 수정이 실제로 해결됐는지 확인할 수 있습니다.
Open /ko, click the language menu, then click the site menu이 설명을 정확한 재현 단계로 정리해줘.
디버깅 순서
Minimal log
Error line + file path + stack line from src실제 실패와 위치를 보존한 짧은 로그 묶음입니다.
첫 오류, 프로젝트 파일 경로, 실행 명령, 최종 성공/실패 요약을 남깁니다.
Error line + file path + stack line from src이 긴 로그를 디버깅에 필요한 최소 줄로 압축해줘.