에러가 났을 때 덜 무서워지는 법

2026-07-09Views 1약 8분생성형 AI 활용

Summary

에러는 실패가 아니라 안내문입니다

Next.js를 배우다 보면 언젠가 빨간 화면을 보게 됩니다. 터미널에 긴 영어 문장이 쏟아지기도 하고, 브라우저 화면 전체가 에러 메시지로 바뀌기도 합니다. 처음 보면 "내가 뭘 망가뜨렸나?"라는 생각이 들 수 있습니다.

하지만 대부분의 에러는 사이트 전체가 망가졌다는 뜻이 아닙니다. 더 정확히 말하면 "이 파일의 이 근처에서 이해할 수 없는 부분을 만났다"는 안내에 가깝습니다. 내비게이션이 길을 잘못 들었을 때 "다음 교차로에서 돌아가세요"라고 말하는 것처럼, 에러 메시지도 수정 위치를 알려 주는 신호입니다.

비개발자에게 중요한 목표는 모든 에러를 혼자 해결하는 것이 아닙니다. 무엇을 봐야 하는지 알고, 원인을 좁히고, 검색이나 AI에게 제대로 질문할 수 있는 상태가 되는 것입니다.

에러가 났을 때 덜 무서워지는 법 AI 생성 이미지

에러 메시지에서 먼저 볼 세 가지

에러 화면을 만나면 긴 문장을 처음부터 끝까지 해석하려고 하지 마세요. 먼저 아래 세 가지만 찾습니다.

파일 이름
예: app/page.tsx, components/Header.tsx
줄 번호
예: 12:5, line 12
보통 12번째 줄 근처라는 뜻입니다.
핵심 문장
예: Unexpected token, Cannot find module, JSX element has no corresponding closing tag

에러 메시지는 보통 길지만, 실제 단서는 이 세 곳에 모여 있습니다. 파일 이름은 "어느 방에서 문제가 났는지", 줄 번호는 "그 방의 어느 위치인지", 핵심 문장은 "무슨 종류의 문제인지"를 알려 줍니다.

예를 들어 이런 메시지가 있다고 해 봅시다.

Error: JSX element 'div' has no corresponding closing tag.
app/page.tsx (18:7)

이 문장을 자연스럽게 바꾸면 이렇습니다.

app/page.tsx 파일 18번째 줄 근처에서 <div> 태그를 열었는데 닫는 태그가 보이지 않습니다.

이제 할 일은 명확합니다. VS Code에서 app/page.tsx를 열고 18번째 줄 주변을 봅니다. 꼭 18번째 줄만 보지 말고, 위아래 5줄 정도를 함께 확인하세요. 에러는 실제 원인보다 조금 아래에서 발견될 때가 많습니다.

브라우저 에러와 터미널 에러 구분하기

Next.js 작업 중 에러를 볼 수 있는 곳은 크게 두 곳입니다.

첫째, 브라우저 화면입니다. http://localhost:3000을 열었을 때 빨간 에러 화면이 나오거나 특정 페이지가 보이지 않는 경우입니다. 브라우저 에러는 주로 "화면을 그리다가 문제가 생겼다"는 뜻입니다.

둘째, 터미널입니다. npm run dev를 실행한 창에 빨간 글씨나 긴 메시지가 나오는 경우입니다. 터미널 에러는 Next.js가 프로젝트를 실행하거나 파일을 읽는 과정에서 문제가 생겼다는 뜻입니다.

쉽게 비유하면 브라우저는 손님이 보는 매장이고, 터미널은 주방입니다. 손님 화면이 이상하면 브라우저를 보고, 주방에서 재료 준비가 멈췄다면 터미널을 봐야 합니다.

다음처럼 판단하면 됩니다.

브라우저에 빨간 화면이 나온다 → 브라우저 에러 문장에서 파일명과 줄 번호를 찾습니다.
브라우저가 계속 로딩만 한다 → 터미널에서 개발 서버가 살아 있는지 확인합니다.
localhost:3000 접속 자체가 안 된다 → 터미널에서 npm run dev가 실행 중인지 확인합니다.
터미널에 command not found, npm error가 나온다 → 프로젝트 실행 환경이나 명령어 문제일 가능성이 큽니다.

특히 브라우저 화면만 새로고침하지 말고, 터미널도 함께 보는 습관을 들이세요. Next.js는 브라우저보다 터미널에 더 자세한 단서를 보여 줄 때가 많습니다.

초보자가 가장 자주 만드는 실수

에러의 원인은 거창하지 않은 경우가 많습니다. 특히 처음에는 아래 실수가 대부분입니다.

괄호가 하나 빠진 경우

코드에는 여러 종류의 괄호가 나옵니다.

()
{}
[]

괄호는 문장 안의 상자입니다. 상자를 열었으면 닫아야 합니다. 예를 들어 return (으로 화면을 열었다면 마지막에 )가 있어야 합니다.

export default function Home() {
  return (
    <main>
      <h1>안녕하세요</h1>
    </main>
  )
}

에러가 났을 때는 커서를 괄호 옆에 두고 VS Code가 짝이 되는 괄호를 표시해 주는지 확인해 보세요.

따옴표가 닫히지 않은 경우

문자에는 따옴표가 필요합니다.

<h1 className="text-3xl">회사 소개</h1>

아래처럼 앞에는 따옴표가 있는데 뒤에 따옴표가 없으면 에러가 납니다.

<h1 className="text-3xl>회사 소개</h1>

디자인을 바꾸려고 className 안에 Tailwind CSS 표현을 추가하다가 자주 생기는 실수입니다. 에러가 나면 className="..."의 시작과 끝이 잘 닫혔는지 먼저 보세요.

태그를 열고 닫지 않은 경우

HTML과 JSX의 태그는 대부분 열고 닫아야 합니다.

<section>
  <h2>서비스</h2>
  <p>작은 브랜드를 위한 웹사이트를 만듭니다.</p>
</section>

<section>을 열었으면 </section>으로 닫습니다. <h2>를 열었으면 </h2>로 닫습니다.

자주 보는 에러 문장은 다음과 같습니다.

JSX element 'section' has no corresponding closing tag.

뜻은 간단합니다.

<section>을 열었는데 닫는 </section>을 찾지 못했습니다.

파일 이름과 대소문자가 다른 경우

컴포넌트를 불러올 때 파일 이름이 정확해야 합니다.

import Header from '@/components/Header'

그런데 실제 파일 이름이 header.tsx라면 문제가 생길 수 있습니다. 어떤 컴퓨터에서는 우연히 동작해도, 배포할 때는 에러가 날 수 있습니다. 그래서 컴포넌트 파일은 처음부터 대소문자를 통일하는 것이 좋습니다.

import 경로가 틀린 경우

import는 다른 파일에서 필요한 것을 가져오는 문장입니다. 냉장고에서 재료를 꺼내 오듯, 다른 파일의 컴포넌트나 데이터를 현재 파일로 가져옵니다.

이런 에러가 보일 수 있습니다.

Module not found: Can't resolve '@/components/Button'

뜻은 이렇습니다.

@/components/Button 위치에서 파일을 찾을 수 없습니다.

이때 확인할 것은 세 가지입니다.

components 폴더가 실제로 있는가?
Button.tsx 파일 이름이 정확한가?
button.tsx, Buttons.tsx처럼 이름이 다르지 않은가?

수정하기 전에 안전장치를 만드세요

에러를 고칠 때 가장 위험한 행동은 당황해서 여러 곳을 한꺼번에 바꾸는 것입니다. 그러면 무엇 때문에 해결됐는지, 무엇 때문에 더 망가졌는지 알기 어렵습니다.

작업 전에는 다음 습관을 추천합니다.

하나씩 바꾸고 저장하기

문구 하나, 클래스 하나, 태그 하나처럼 작은 단위로 바꾸세요. 저장한 뒤 브라우저를 확인합니다. 문제가 없으면 다음 수정으로 넘어갑니다.

한 번에 30줄을 고치면 에러가 났을 때 범위가 너무 넓어집니다. 반대로 한 번에 3줄만 고치면 방금 바꾼 곳만 보면 됩니다.

되돌리기를 두려워하지 않기

VS Code에서 되돌리기는 가장 중요한 안전장치입니다.

Windows: Ctrl + Z
Mac: Command + Z

에러가 난 직후라면 먼저 한 번 되돌리고 저장해 보세요. 화면이 다시 정상으로 돌아오면 방금 수정한 부분에 원인이 있다는 뜻입니다.

큰 수정 전에는 복사본 만들기

아직 Git에 익숙하지 않다면 큰 수정 전에 파일 내용을 복사해 메모장에 붙여 두어도 됩니다. 세련된 방법은 아니지만 초보 단계에서는 충분히 좋은 백업입니다.

예를 들어 app/page.tsx 전체를 바꾸기 전에는 기존 내용을 잠시 따로 저장해 둡니다. 문제가 생기면 다시 붙여 넣으면 됩니다.

Git을 사용한다면 더 좋습니다. Git은 작업 기록을 저장하는 도구입니다. 문서 편집기의 "버전 기록"처럼, 예전 상태로 돌아갈 수 있게 해 줍니다. Git은 다음 장에서 배포와 함께 다루겠지만, 지금은 "큰 변경 전에는 되돌아갈 지점을 만들어야 한다"는 생각만 기억하면 됩니다.

자주 만나는 에러 문장 읽기

아래 문장들은 Next.js 초보자가 자주 만나는 에러입니다. 영어를 전부 외울 필요는 없습니다. 핵심 표현만 익히면 됩니다.

Module not found

파일이나 라이브러리를 찾지 못했다는 뜻입니다. import 경로, 파일 이름, 설치 여부를 확인합니다.

Unexpected token

예상하지 못한 기호가 나왔다는 뜻입니다. 괄호, 쉼표, 따옴표, 태그 위치를 확인합니다.

Expected corresponding JSX closing tag

닫는 태그가 필요하다는 뜻입니다. <div>와 </div>, <section>과 </section>이 짝을 이루는지 봅니다.

Cannot read properties of undefined

아직 없는 값에서 무언가를 읽으려고 했다는 뜻입니다. 데이터 이름을 잘못 썼거나, 값이 준비되기 전에 화면에서 사용했을 수 있습니다. 비개발자라면 이 에러는 혼자 오래 붙잡기보다 개발자나 AI에게 상황을 함께 보여 주는 편이 좋습니다.

Hydration failed

서버에서 만든 화면과 브라우저에서 다시 확인한 화면이 서로 다르다는 뜻입니다. 전문 용어인 하이드레이션은 "미리 만들어 온 화면에 브라우저가 동작을 연결하는 과정" 정도로 이해하면 됩니다. 날짜, 랜덤 숫자, 브라우저에서만 알 수 있는 값 때문에 생길 수 있어 초보자에게는 조금 어려운 에러입니다. 이 경우 검색이나 질문을 적극 활용하세요.

검색하거나 AI에게 물어볼 때 넣어야 할 정보

에러를 검색하거나 AI에게 물어볼 때 "Next.js 에러가 나요"라고만 쓰면 좋은 답을 받기 어렵습니다. 병원에 가서 "아파요"라고만 말하는 것과 비슷합니다. 어디가, 언제부터, 무엇을 했더니 아픈지 말해야 진단이 쉬워집니다.

질문에는 아래 정보를 넣으세요.

사용 중인 도구
예: Next.js App Router, TypeScript, Tailwind CSS
무엇을 하려 했는지
예: components/Header.tsx를 만들고 layout.tsx에서 불러오려 했다
전체 에러 메시지 중 핵심 부분
예: Module not found: Can't resolve '@/components/Header'
관련 코드 일부
전체 파일이 아니라 에러가 난 줄 주변 10~20줄 정도
이미 확인한 것
예: 파일 이름은 Header.tsx이고, 위치는 components 폴더 안이다

AI에게 질문할 때는 이렇게 쓰면 좋습니다.

Next.js App Router 프로젝트를 만들고 있습니다.
components/Header.tsx 파일을 만든 뒤 app/layout.tsx에서 import 했는데 에러가 납니다.

에러 메시지:
Module not found: Can't resolve '@/components/Header'

관련 코드:
import Header from '@/components/Header'

확인한 것:
- components 폴더는 프로젝트 최상위에 있습니다.
- 파일 이름은 Header.tsx입니다.
- npm run dev는 실행 중입니다.

비개발자도 이해할 수 있게 확인 순서를 알려 주세요.

이렇게 질문하면 AI도 더 정확하게 답할 수 있습니다. 개발자에게 도움을 요청할 때도 마찬가지입니다. 에러 화면 캡처만 보내는 것보다, 어떤 파일을 수정했는지 함께 알려 주면 해결 시간이 크게 줄어듭니다.

혼자 해결할 수 있는 일과 맡기면 좋은 일

비개발자가 직접 확인해 볼 만한 일은 다음과 같습니다.

파일 이름 오타 확인
태그 닫기 확인
괄호와 따옴표 확인
import 경로 확인
npm run dev 실행 여부 확인
최근 수정한 부분 되돌리기
에러 메시지에서 파일명과 줄 번호 찾기

반대로 아래 상황은 전문가에게 맡기는 것이 좋습니다.

로그인, 결제, 개인정보 저장과 관련된 에러
배포 후에만 발생하는 서버 오류
데이터베이스 연결 문제
보안 경고
원인을 모르고 같은 에러가 반복되는 경우
Hydration failed처럼 화면 생성 방식과 관련된 복잡한 오류

직접 할 수 있는 일과 맡길 일을 구분하는 것도 중요한 실력입니다. 모든 문제를 혼자 해결하려고 하면 지치기 쉽습니다. 대신 기본 점검을 한 뒤, 필요한 정보를 정리해 도움을 요청하면 됩니다.

에러가 났을 때의 기본 순서

마지막으로, 에러가 났을 때는 아래 순서대로 움직이세요.

숨을 고르고 최근에 바꾼 파일을 떠올립니다.
브라우저와 터미널 중 어디에 에러가 보이는지 확인합니다.
에러 메시지에서 파일 이름, 줄 번호, 핵심 문장을 찾습니다.
해당 파일의 줄 번호 위아래를 확인합니다.
괄호, 따옴표, 태그 닫기, 파일 이름 오타를 먼저 봅니다.
방금 수정한 부분을 작게 되돌려 봅니다.
해결되지 않으면 에러 메시지와 상황을 정리해 검색하거나 AI에게 질문합니다.

빨간 화면은 끝이 아닙니다. 오히려 어디를 봐야 할지 알려 주는 시작점입니다. 에러를 완전히 피하는 사람은 없습니다. 대신 좋은 작업자는 에러가 났을 때 당황하지 않고, 단서를 따라가며 문제를 좁혀 갑니다.

Next.js를 배우는 과정에서도 마찬가지입니다. 이제 빨간 화면을 보면 "망했다"가 아니라 "어느 파일, 몇 번째 줄, 어떤 문장부터 볼까?"라고 생각하면 됩니다.

책 목록

비개발자를 위한 Next.js 입문

전체 목차 보기