핵심 요약

expected unqualified-id before numeric constant 에러는 #define MAX_SIZE 100 같은 매크로가 변수·멤버·함수 이름 자리에 그대로 펼쳐져서, 이름이 들어가야 할 곳에 숫자(100)가 남을 때 납니다. 매크로와 다른 이름을 쓰거나, 매크로를 constexpr 상수로 바꾸거나, 꼭 필요하면 충돌 지점 앞에서 #undef 합니다.

멀쩡해 보이는 멤버 변수 선언에서 expected unqualified-id before numeric constant 에러가 나면 당황스럽기 쉽습니다. 이 글은 2026-10-21(KST)에 g++ (Debian 14.2.0-19) 14.2.0으로 직접 재현한 코드와 실제 컴파일러 출력을 바탕으로 원인과 해결 방법을 정리합니다.

한 줄 답: 매크로(#define MAX_SIZE 100)가 이름 자리에 펼쳐져 숫자가 남을 때 발생합니다. 이름 변경, constexpr, #undef 중 하나로 해결합니다.

expected unqualified-id before numeric constant 에러란 무엇인가요?

한 줄 답: 이름(식별자)이 와야 할 곳에 숫자 상수가 왔다는 뜻입니다. unqualified-id는 한정자(Foo:: 같은 접두)가 붙지 않은 이름을 말합니다.

아래는 bad.cpp입니다. 멤버 이름이 매크로 이름과 같습니다.

#define MAX_SIZE 100

struct Config {
    int MAX_SIZE = 10;   // 매크로 이름과 같은 멤버 이름
};

int main() {
    Config c;
    return c.MAX_SIZE;
}

g++ -std=c++17 -c bad.cpp의 실제 출력입니다(종료 코드 1).

$ g++ -std=c++17 -c bad.cpp
bad.cpp:1:18: error: expected unqualified-id before numeric constant
    1 | #define MAX_SIZE 100
      |                  ^~~
bad.cpp:4:9: note: in expansion of macro ‘MAX_SIZE’
    4 |     int MAX_SIZE = 10;   // 매크로 이름과 같은 멤버 이름
      |         ^~~~~~~~
bad.cpp: In function ‘int main()’:
bad.cpp:1:18: error: expected unqualified-id before numeric constant
    1 | #define MAX_SIZE 100
      |                  ^~~
bad.cpp:9:14: note: in expansion of macro ‘MAX_SIZE’
    9 |     return c.MAX_SIZE;
      |              ^~~~~~~~
bad.cpp:9:14: error: expected ‘;’ before numeric constant
    9 |     return c.MAX_SIZE;
      |              ^
      |              ;

왜 매크로 이름 충돌이 원인이 되나요?

한 줄 답: 전처리기가 컴파일 전에 매크로 이름을 글자 그대로 치환하기 때문입니다.

컴파일러는 MAX_SIZE라는 이름을 보지 못하고, 전처리가 끝난 결과만 봅니다. g++ -E -P bad.cpp로 전처리 결과를 확인하면 다음과 같습니다.

$ g++ -E -P bad.cpp
struct Config {
    int 100 = 10;
};
int main() {
    Config c;
    return c. 100;
}
  • 치환 전: int MAX_SIZE = 10; → 치환 후: int 100 = 10;
  • 치환 전: return c.MAX_SIZE; → 치환 후: return c. 100;
  • 이름이 와야 할 자리에 숫자 100이 있으니 “expected unqualified-id before numeric constant”가 됩니다.

출력은 이렇게 읽습니다.

  • error는 bad.cpp:1:18, 즉 #define MAX_SIZE 100의 100을 가리킵니다. 치환된 숫자가 원래 있던 위치입니다.
  • 바로 아래 note: in expansion of macro ‘MAX_SIZE’가 실제로 매크로를 쓴 자리(4:9, 9:14)를 알려줍니다. 고쳐야 할 곳은 이 note 쪽입니다.
  • 세 번째 expected ‘;’ before numeric constant는 c. 100에서 이어서 나온 후속 에러로 볼 수 있습니다.

매크로 MAX_SIZE가 멤버 선언과 c.MAX_SIZE 접근에서 100으로 치환되어 int 100 = 10과 return c. 100이 되는 전처리 흐름 도식

어떻게 고치나요?

한 줄 답: 매크로와 다른 이름을 쓰거나, constexpr로 대체하거나, 충돌 지점 앞에서 #undef 합니다.

  1. 이름 변경: 멤버 이름을 max_size처럼 매크로와 다르게 바꿉니다.
  2. constexpr로 대체: 매크로 대신 constexpr int kMaxSize = 100;을 씁니다. 상수는 일반 이름처럼 스코프 규칙을 따르므로 이런 치환이 일어나지 않습니다.
  3. #undef: 충돌하는 선언 앞에서 #undef MAX_SIZE를 씁니다. 이후에 포함하는 헤더가 그 매크로를 필요로 할 수 있으니 순서에 주의해야 합니다.
  4. 이름 규칙: 매크로 이름은 ALL_CAPS로 쓰고, 일반 변수·멤버 이름에는 대문자만으로 된 이름을 쓰지 않습니다.

①과 ②를 적용한 good.cpp입니다.

#define MAX_SIZE 100

struct Config {
    int max_size = 10;   // 매크로와 다른 이름 사용
};

constexpr int kMaxSize = 100;  // 매크로 대신 constexpr

int main() {
    Config c;
    return c.max_size + kMaxSize - MAX_SIZE;
}
$ g++ -std=c++17 good.cpp -o good && ./good; echo $?
10

③을 적용한 undef.cpp입니다.

#define MAX_SIZE 100

#undef MAX_SIZE
struct Config {
    int MAX_SIZE = 10;   // 매크로 이름과 같은 멤버 이름
};

int main() {
    Config c;
    return c.MAX_SIZE;
}
$ g++ -std=c++17 -c undef.cpp
$ echo $?
0

good.cpp는 컴파일되고 종료 코드 10으로 실행되었으며, undef.cpp는 컴파일에 성공했습니다(종료 코드 0).

키워드 explicit처럼 C++의 다른 함정이 궁금하시면 C++ explicit 글도 참고해 주시기 바랍니다.

헤더에서 온 매크로라면 어떻게 찾나요?

한 줄 답: note에 적힌 파일:줄 번호를 보고, g++ -E 출력에서 해당 이름을 검색합니다.

  • 매크로를 직접 만들지 않았다면 note: in expansion of macro가 알려주는 위치를 먼저 확인합니다.
  • g++ -E 출력을 파일로 저장해 의심되는 이름을 검색하면 치환된 결과를 바로 볼 수 있습니다. 변환된 코드를 눈으로 보는 방법으로는 C++ Insights 글도 있습니다.
  • 대표적인 예가 Windows 헤더의 min/max입니다. Microsoft Learn의 “max macro (Minwindef.h)” 문서에는 #define max(a, b) (((a) > (b)) ? (a) : (b))로 정의되어 있습니다(문서 링크). 함수처럼 생긴 매크로라 std::max 같은 이름도 영향을 받을 수 있습니다.
  • <windows.h>를 포함하기 전에 #define NOMINMAX를 두어 이 매크로가 정의되지 않게 하는 방법이 널리 쓰입니다.
  • 다른 방법으로, (std::max)(a, b)처럼 이름을 괄호로 감싸 호출할 수도 있습니다.
  • 디버깅 자체가 필요하다면 gdb 글을 참고해 주시기 바랍니다.

자주 묻는 질문은 무엇인가요?

한 줄 답: 아래 세 가지가 가장 흔한 질문입니다.

Q1. 매크로 없이도 같은 메시지가 나나요?

나올 수 있습니다. 예를 들어 함수 밖에 return 1; 같은 구문을 쓰면 같은 g++ 14.2.0에서 error: expected unqualified-id before ‘return’이 나옵니다. 뒤에 붙는 말이 numeric constant가 아니라는 점이 다릅니다. 이때는 매크로가 아니라 문장의 위치를 확인해야 합니다.

Q2. enum이나 상수 이름에도 생기나요?

생깁니다. 이름이 올 수 있는 모든 식별자 자리(변수, 멤버, 함수, enum 값 등)에서 같은 방식으로 치환되기 때문입니다.

Q3. 매크로를 꼭 써야 할 때는 어떻게 하나요?

MYLIB_MAX_SIZE처럼 프로젝트 접두어를 붙여 다른 이름과 겹칠 가능성을 줄입니다.

함께 보면 좋은 글은 무엇인가요?

한 줄 답: C++ explicit, C++ Insights, gdb 글입니다.

출처는 어디인가요?

한 줄 답: 직접 실행한 GCC 결과와 Microsoft Learn 문서입니다.