핵심 요약
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에서 이어서 나온 후속 에러로 볼 수 있습니다.

어떻게 고치나요?
한 줄 답: 매크로와 다른 이름을 쓰거나, constexpr로 대체하거나, 충돌 지점 앞에서 #undef 합니다.
- 이름 변경: 멤버 이름을
max_size처럼 매크로와 다르게 바꿉니다. - constexpr로 대체: 매크로 대신
constexpr int kMaxSize = 100;을 씁니다. 상수는 일반 이름처럼 스코프 규칙을 따르므로 이런 치환이 일어나지 않습니다. - #undef: 충돌하는 선언 앞에서
#undef MAX_SIZE를 씁니다. 이후에 포함하는 헤더가 그 매크로를 필요로 할 수 있으니 순서에 주의해야 합니다. - 이름 규칙: 매크로 이름은
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 문서입니다.
- GCC 직접 실행: g++ (Debian 14.2.0-19) 14.2.0, 2026-10-21 (KST)
- Microsoft Learn, max macro (Minwindef.h) (2026-10-21 확인)