SyntaxError: Unexpected token, 오류 뜻부터 해결 방법까지 한 번에

SyntaxError: Unexpected token, 오류 뜻부터 해결 방법까지 한 번에

자바스크립트 코드를 작성하다 보면 콘솔에 SyntaxError: Unexpected token이라는 메시지가 나타날 때가 있습니다.

코드가 길어질수록 어디가 잘못됐는지 한눈에 찾기 어려워 답답하게 느껴질 수 있는데요.
 
하지만 이 오류는 대부분 자바스크립트 문법 규칙에 맞지 않는 문자나 기호가 들어갔을 때 발생합니다.

오늘은 SyntaxError: Unexpected token의 정확한 뜻부터 가장 흔한 발생 원인, 빠르게 해결하는 디버깅 순서까지 한 번에 정리해보겠습니다.
 
 

SyntaxError: Unexpected token이란?

SyntaxError는 자바스크립트 엔진이 코드를 해석하는 과정에서 문법적으로 이해할 수 없는 부분을 발견했을 때 발생하는 오류입니다. 여기서 Unexpected token은 말 그대로 “예상하지 못한 토큰을 만났다”는 의미입니다.

토큰은 코드 안에 있는 괄호, 쉼표, 문자열, 키워드, 연산자 같은 작은 문법 요소라고 생각하면 쉽습니다. 즉 엔진이 “이 위치에는 이런 문자가 나오면 안 되는데?”라고 판단한 상황입니다.

console.log("hello";
 
// SyntaxError
// 닫는 괄호가 빠져 있음

 
이처럼 오류 메시지가 표시된 줄만 볼 것이 아니라 바로 앞쪽 코드까지 함께 확인하는 것이 중요합니다. 실제 문법 오류는 이전 줄에서 시작됐지만 다음 줄에서 발견되는 경우도 많기 때문입니다.
 
 

Unexpected token 오류, 가장 흔한 원인 10가지

1. 괄호 짝이 맞지 않는 경우
소괄호 (), 중괄호 {}, 대괄호 [] 중 하나를 빠뜨리거나 잘못 닫으면 자주 발생합니다. 함수나 조건문이 여러 단계로 중첩된 코드일수록 먼저 괄호 짝을 확인해 보세요.

 
2. 따옴표를 닫지 않은 경우
문자열을 작성하면서 작은따옴표나 큰따옴표를 닫지 않으면 이후 코드까지 문자열로 인식될 수 있습니다. 문자열이 긴 경우 특히 놓치기 쉬운 부분입니다.

const message = "안녕하세요;
// 닫는 따옴표 누락

 
3. 쉼표 위치가 잘못된 경우
객체나 배열을 작성할 때 필요한 쉼표가 빠지거나 문법적으로 허용되지 않는 위치에 들어가면 오류가 발생할 수 있습니다. 객체 속성이 연속해서 이어질 때 자주 나타납니다.

const user = {
  name: "민수"
  age: 20
};
// name 뒤 쉼표 누락

 
4. 중괄호를 잘못 닫은 경우
if문이나 함수, 객체를 여러 개 사용하다 보면 닫는 중괄호 위치가 뒤섞일 수 있습니다. 코드 자동 정렬 기능을 이용하면 중괄호 구조가 어긋난 부분을 쉽게 발견할 수 있습니다.
 

5. JSON 문법이 잘못된 경우
JSON에서는 속성 이름과 문자열에 큰따옴표를 사용하는 것이 기본 규칙입니다. 자바스크립트 객체 문법과 JSON을 혼동하면 JSON.parse() 과정에서도 SyntaxError가 발생할 수 있습니다.

const json = '{"name":"민수",}';
JSON.parse(json);
// 잘못된 JSON 문법

 

6. HTML이나 JSX 문법이 섞인 경우
일반 자바스크립트 파일에 JSX나 HTML 태그를 그대로 작성하면 환경에 따라 Unexpected token '<' 같은 오류가 나타날 수 있습니다. React 프로젝트라면 JSX 변환 설정이 정상인지 함께 확인하세요.

 

7. import와 export 문법을 잘못 사용한 경우
모듈 환경이 아닌 곳에서 import를 사용하거나, import/export 문법 자체를 잘못 작성하면 SyntaxError가 발생할 수 있습니다. 브라우저에서는 상황에 따라 <script type="module"> 설정도 필요합니다.

 

8. 템플릿 리터럴 백틱을 잘못 사용한 경우
템플릿 리터럴은 작은따옴표가 아닌 백틱 `을 사용합니다. 백틱이 닫히지 않았거나 ${} 내부의 중괄호가 맞지 않으면 문법 오류가 발생하기 쉽습니다.

const name = "민수";
const message = `안녕하세요 ${name}`;

 

9. 예약어나 키워드를 잘못 사용한 경우
const, let, return, function 같은 키워드를 문법에 맞지 않는 위치에서 사용하면 SyntaxError가 발생합니다. 특히 return은 함수 밖에서 사용할 수 없는 환경이 있다는 점도 확인해야 합니다.

 
10. 복사한 코드에 특수문자가 포함된 경우
웹페이지나 문서에서 코드를 복사하면 일반 따옴표 대신 스마트 따옴표가 들어가거나 보이지 않는 특수문자가 포함될 수 있습니다. 눈으로는 비슷해 보여도 자바스크립트 엔진에서는 다른 문자로 인식할 수 있으므로 직접 다시 입력해 보는 것도 방법입니다.
 
 

SyntaxError 해결 방법, 가장 빠른 순서

Unexpected token 오류가 발생했다면 먼저 콘솔에 표시된 파일 이름과 줄 번호를 확인하세요. 그다음 오류가 발생한 줄뿐 아니라 위쪽 2~3줄까지 함께 살펴보는 것이 좋습니다.
 

두 번째는 괄호와 따옴표의 짝을 확인하는 것입니다. SyntaxError의 상당수는 (), {}, [], 따옴표 중 하나가 빠져 발생합니다. VS Code 같은 편집기의 괄호 색상 표시와 자동 들여쓰기를 활용하면 빠르게 찾을 수 있습니다.

 

확인 순서	점검할 내용
1단계	에러 메시지의 파일과 줄 번호 확인
2단계	오류 줄과 바로 위 코드 함께 확인
3단계	괄호와 따옴표 짝 확인
4단계	쉼표와 세미콜론 위치 확인
5단계	JSON 또는 JSX 문법 여부 확인
6단계	import/export 실행 환경 확인
7단계	코드 포맷터와 린터로 재검사

 
 

Unexpected token '<'가 나타난다면?

웹 개발에서는 Unexpected token '<' 오류도 자주 볼 수 있습니다. 이 경우 자바스크립트나 JSON을 받아야 하는 위치에서 실제로는 HTML 문서가 반환됐을 가능성이 있습니다.

 
예를 들어 API 요청 주소가 잘못되어 서버의 404 HTML 페이지가 반환됐는데 이를 JSON으로 처리하려고 하면 비슷한 오류가 발생할 수 있습니다. 이럴 때는 브라우저 개발자 도구의 Network 탭에서 실제 응답 내용을 확인해 보세요.
 
 

Unexpected token 오류를 예방하는 방법

코드를 작성할 때는 Prettier 같은 포맷터와 ESLint 같은 정적 분석 도구를 활용하면 문법 오류를 훨씬 빠르게 발견할 수 있습니다. 자동 저장과 함께 포맷팅을 적용해 두면 괄호나 들여쓰기 실수를 확인하기도 쉬워집니다.
 
또한 한 번에 많은 코드를 작성하기보다 작은 단위로 실행하면서 확인하는 습관도 도움이 됩니다. 오류가 발생했을 때 수정해야 할 범위가 좁아지기 때문에 원인을 찾는 시간이 크게 줄어듭니다.
 
 
SyntaxError: Unexpected token은 자바스크립트 엔진이 현재 코드에서 예상하지 못한 문법 요소를 만났다는 의미입니다.

괄호, 따옴표, 쉼표, JSON, JSX, import/export, 템플릿 리터럴 순으로 확인하면 대부분의 문제를 빠르게 해결할 수 있습니다.
 
에러가 표시된 한 줄만 보지 말고 바로 앞 코드까지 함께 살펴보는 것이 핵심입니다.

처음에는 막막해 보여도 문법 구조를 차근차근 확인하면 생각보다 쉽게 원인을 찾을 수 있으니 하나씩 점검해 보세요.