자주 만나는 에러 10가지

여기서는 초보자가 가장 자주 만나는 에러 10가지를 정리합니다. 지금 다 외울 필요는 없습니다. 에러가 나왔을 때 이 페이지를 찾아보시면 됩니다.

에러 사전

번호	에러 메시지	무슨 뜻인지	해결 방법
1	`Module not found: Can't resolve '...'`	필요한 부품이 설치 안 됨	터미널에서 `npm install` 실행
2	`Cannot read properties of undefined`	아직 준비되지 않은 데이터를 사용하려 함	AI에게 에러를 보여주고 수정 요청
3	`Port 3000 is already in use`	다른 프로그램이 이미 3000번을 쓰고 있음	다른 터미널을 닫거나, `npm run dev -- -p 3001` 실행
4	`NEXT_PUBLIC_SUPABASE_URL is not defined`	환경 설정 파일이 없음	`.env.local` 파일이 있는지 확인
5	`git: command not found`	Git이 설치되어 있지 않음	Git을 설치 (1편에서 했던 방법 참고)
6	`Hydration failed`	서버와 브라우저의 내용이 다름	AI에게 에러를 보여주고 수정 요청
7	`401 Unauthorized`	비밀번호(API 키)가 틀리거나 만료됨	API 키를 확인하고 다시 입력
8	`npm ERR!`	설치 과정에서 문제 발생	`node_modules` 폴더 삭제 후 `npm install` 다시 실행
9	`SyntaxError: Unexpected token`	코드에 오타가 있음	AI에게 해당 파일을 확인해달라고 요청
10	`Build failed`	배포용 빌드 중 에러 발생	`npm run build`를 먼저 로컬에서 실행해 보고 에러 수정

"부품이 없다"는 뜻입니다.

레시피에 "올리브유"가 필요한데 냉장고에 없는 것과 같습니다. 필요한 부품을 설치하면 됩니다.


npm install lucide-react

AI가 코드에서 사용한 부품 이름을 알려줄 테니, 그대로 설치하면 됩니다.

"아직 준비 안 됐는데 쓰려고 했다"는 뜻입니다.

데이터를 인터넷에서 가져오는 중인데, 다 가져오기도 전에 사용하려고 할 때 나타납니다. AI에게 보여주면 "데이터가 준비될 때까지 기다리는 코드"를 추가해 줍니다.

"이미 다른 프로그램이 이 자리를 쓰고 있다"는 뜻입니다.

이전에 실행한 개발 서버가 아직 돌아가고 있을 때 나타납니다. 다른 터미널 창을 확인해서 닫거나, 다른 번호(3001)를 사용하면 됩니다.

"비밀 정보가 담긴 파일을 못 찾겠다"는 뜻입니다.

프로젝트 폴더에 .env.local 파일이 있는지 확인하세요. 이 파일에는 데이터베이스 주소나 API 키 같은 정보가 들어있습니다.

위 표를 참고하시고, 해결이 안 되면 에러 메시지 전체를 AI에게 보여주세요. AI가 상황에 맞는 해결 방법을 알려줍니다.

어떤 에러든 이 순서를 따르면 대부분 해결됩니다:

이 다섯 단계를 기억하세요. 에러가 나와도 이 순서대로 하면 항상 해결할 수 있습니다.