Identifier has already been declared, 뜻부터 해결법까지

자바스크립트 코드를 실행했는데 SyntaxError: Identifier 'name' has already been declared 같은 메시지가 나타날 때가 있습니다.

분명 평소처럼 변수를 선언했을 뿐인데 갑자기 코드가 실행되지 않으면 어떤 부분부터 확인해야 할지 헷갈릴 수 있는데요.

Identifier has already been declared는 쉽게 말해 “같은 이름을 이미 선언했는데 또 선언했다”는 의미입니다.

이번 글에서는 identifier가 무엇인지부터 중복 선언이 발생하는 대표적인 원인, 재선언과 재할당의 차이, 빠르게 해결하는 순서까지 알아보겠습니다.

Identifier has already been declared 뜻은?

먼저 identifier(식별자)는 변수명, 함수명, 클래스명처럼 코드에서 어떤 대상을 구분하기 위해 사용하는 이름을 뜻합니다.

예를 들어 userName이라는 변수를 만들었다면 userName이 하나의 식별자입니다.

let userName = "민수";
let userName = "지민";
// SyntaxError:
// Identifier 'userName' has already been declared

위 코드에서는 같은 범위 안에서 userName을 let으로 두 번 선언했습니다. 이미 해당 이름이 존재하기 때문에 자바스크립트가 같은 이름을 다시 선언할 수 없다고 알려주는 것입니다.

중복 선언과 재할당, 무엇이 다를까?

이 오류를 이해하려면 재선언과 재할당의 차이를 알아두는 것이 좋습니다. 재선언은 let이나 const 같은 키워드를 사용해 같은 이름의 변수를 다시 만드는 것이고, 재할당은 이미 존재하는 변수에 새로운 값을 넣는 것입니다.

// 잘못된 예: 재선언
let score = 80;
let score = 100;
// 올바른 예: 재할당
let score = 80;
score = 100;

값만 변경하고 싶은 상황이라면 두 번째 let을 다시 작성할 필요가 없습니다. 변수는 한 번 선언하고 이후에는 필요한 경우 값만 변경한다고 기억하면 이해하기 쉽습니다.

Identifier has already been declared 원인 8가지

1. 같은 변수를 let으로 두 번 선언한 경우
가장 흔한 원인입니다. 같은 스코프에서 동일한 변수명을 let으로 다시 선언하면 SyntaxError가 발생합니다.

2. const 변수를 중복 선언한 경우
const 역시 같은 스코프에서 같은 이름으로 다시 선언할 수 없습니다. 값을 바꿀 필요가 있다면 애초에 해당 값에 const가 적절한지도 함께 확인하세요.

const API_URL = "https://example.com";
const API_URL = "https://example.org";
// 중복 선언

3. let과 const에 같은 이름을 사용한 경우
첫 번째는 let이고 두 번째는 const라고 해서 다른 변수로 취급되는 것은 아닙니다. 동일한 스코프에 같은 이름이 존재한다면 충돌합니다.

let user = "민수";
const user = "지민";
// SyntaxError

4. 함수·클래스 등 다른 선언과 이름이 충돌한 경우
변수만 검색해서는 원인을 발견하지 못하는 경우도 있습니다. 함수, 클래스 등 다른 선언에서 같은 식별자를 사용하고 있는지 주변 코드를 함께 확인해 보세요. 구체적인 허용 여부는 선언 종류와 실행 환경에 따라 달라질 수 있습니다.

5. import한 이름과 로컬 선언이 겹친 경우
다른 모듈에서 가져온 이름 역시 현재 모듈에서 사용하는 식별자입니다. import한 이름과 동일한 이름을 다시 선언하면 충돌할 수 있습니다.

import { getUser } from "./user.js";
const getUser = "test";
// 이름 충돌

둘 다 필요한 상황이라면 import할 때 별칭을 사용하는 방법도 있습니다.

import { getUser as fetchUser } from "./user.js";
const getUser = "test";

6. 함수 매개변수와 내부 선언 이름이 충돌한 경우
함수의 매개변수 역시 해당 함수 안에서 사용할 수 있는 이름입니다. 같은 함수 블록에서 매개변수와 충돌하는 lexical 선언을 만들면 문제가 될 수 있습니다.

function showUser(name) {
  let name = "민수";
}
// name 중복

7. 코드를 복사하면서 기존 선언을 남겨둔 경우
비슷한 기능을 만들기 위해 코드를 복사한 뒤 변수명 변경을 빠뜨리는 경우도 많습니다. 코드가 길다면 에디터의 전체 검색 기능으로 에러 메시지에 나온 이름을 검색해 보세요.

8. 스크립트·모듈 구성 때문에 예상하지 못한 충돌이 생긴 경우
여러 스크립트의 실행 방식이나 모듈 구성에 따라 이름이 사용되는 범위를 잘못 이해하면 중복 선언 문제가 발생할 수 있습니다. 특히 코드를 합치거나 번들링하는 과정에서 오류가 생겼다면 어떤 파일에서 같은 이름이 선언되는지 확인하는 것이 좋습니다.

Identifier 오류 해결 순서 7단계

가장 먼저 콘솔에서 어떤 identifier가 중복됐는지 확인하세요. 예를 들어 Identifier 'user' has already been declared라고 나온다면 가장 먼저 검색해야 할 단어는 user입니다.

VS Code를 사용한다면 현재 파일 검색뿐 아니라 프로젝트 전체 검색을 활용하는 것도 좋습니다. 같은 이름이 여러 번 발견되면 각각 어떤 키워드로 선언되어 있는지 확인합니다.

순서	확인할 내용
1단계	에러 메시지에서 중복된 이름 확인
2단계	해당 이름을 현재 파일에서 검색
3단계	필요하면 프로젝트 전체 검색
4단계	let, const, import, 함수·클래스 선언 확인
5단계	두 선언이 같은 스코프인지 확인
6단계	불필요한 선언 제거 또는 이름 변경
7단계	저장 후 다시 실행해 오류 확인

같은 변수명을 쓰고 싶다면 스코프를 확인하세요

같은 이름을 코드 전체에서 절대 사용할 수 없다는 뜻은 아닙니다. 서로 다른 블록 스코프라면 let이나 const에 같은 이름을 사용할 수 있습니다.

const name = "민수";
if (true) {
  const name = "지민";
  console.log(name); // 지민
}
console.log(name); // 민수

중괄호 { } 내부에 선언된 두 번째 name은 바깥의 name과 다른 스코프에 있습니다. 따라서 Identifier has already been declared 오류가 발생했다면 이름만 보는 것이 아니라 두 선언이 같은 범위에 있는지 확인하는 것이 중요합니다.

var로 바꾸면 해결될까?

중복 선언 오류가 발생했다고 무조건 let이나 const를 var로 변경하는 것은 좋은 해결 방법이 아닙니다. var는 let·const와 스코프 및 재선언 규칙이 다르기 때문에 오류가 사라지는 것처럼 보여도 새로운 혼란을 만들 수 있습니다.

먼저 왜 같은 이름을 두 번 선언했는지 확인하세요. 단순히 값을 변경하려는 목적이었다면 재선언을 제거하고 재할당하면 되고, 서로 다른 값을 의미한다면 변수명을 명확하게 나누는 편이 좋습니다.

// 불필요한 중복 선언
let price = 1000;
let price = 2000;
// 값 변경이 목적이라면
let price = 1000;
price = 2000;

Identifier 중복 선언을 예방하는 방법

변수명을 data, value, result처럼 지나치게 일반적으로만 작성하면 프로젝트가 커질수록 충돌 가능성이 높아집니다.

userData, orderResult처럼 역할을 알 수 있는 이름을 사용하면 코드 이해와 중복 방지에 도움이 됩니다.

또한 ESLint와 에디터의 변수 참조 기능을 활용하면 중복 선언이나 사용하지 않는 변수를 빠르게 확인할 수 있습니다. 코드를 복사해 사용할 때도 기존 변수와 이름이 겹치지 않는지 확인하는 습관을 들여보세요.

Identifier has already been declared는 쉽게 말해 “현재 범위에 이미 존재하는 이름을 다시 선언하려고 했다”는 의미입니다. 오류가 발생하면 에러 메시지에 나온 식별자를 검색하고 같은 스코프에 중복 선언이 있는지부터 확인하세요.

값만 변경하려는 것이라면 다시 선언하지 말고 재할당하고, 서로 다른 용도의 값이라면 이름을 변경하거나 적절한 스코프로 분리하면 됩니다.

앞서 살펴본 Missing initializer 오류와 함께 let, const, 스코프의 기본 규칙을 이해해 두면 비슷한 SyntaxError도 훨씬 쉽게 해결할 수 있습니다.

도전 바이브코딩

Identifier has already been declared, 뜻부터 해결법까지