LaTeX 오류 메시지는 ! 뒤의 첫 몇 단어만 봐도 누가 항의하고 있는지 알 수 있게 만들어져 있습니다. 아무 접두사도 없는 ! Missing $ inserted.는 TeX 엔진 자신이, ! LaTeX Error:는 LaTeX 커널이, ! Package hyperref Error:는 이름이 적힌 그 패키지가 말하는 것입니다. 이 구별을 읽을 줄 알면 첫 줄만으로 고칠 자리가 내 원고인지, 프리앰블의 로드 순서인지, 아니면 남의 버그 추적기인지가 정해집니다. 이 페이지는 실제로 자주 마주치는 메시지를 원문 그대로 늘어놓고, 각각이 정말로 무슨 뜻인지와 깊이 다루는 페이지로 가는 길을 붙인 색인입니다. 여기 실린 메시지는 모두 TeX Live 2024에서 직접 재현해 확인했습니다.
! 다음 단어가 발신자를 알려 줍니다: TeX, LaTeX, 패키지, 경고
!로 시작하는 줄은 오류이며 빌드를 멈출 수 있고, !가 없는 줄은 경고나 안내이며 빌드는 계속됩니다. 그리고 오류 쪽은 ! 바로 뒤의 단어에 따라 세 층으로 나뉩니다. 맨 아래층은 TeX 엔진으로, 그 메시지에는 접두사가 전혀 없습니다. ! Missing $ inserted.는 40년 동안 한 글자도 바뀌지 않았고, LaTeX을 올리지 않은 순수 TeX도 똑같은 문장을 출력합니다. 가운데 층은 LaTeX 커널의 ! LaTeX Error: …, 맨 위층은 패키지와 클래스의 ! Package X Error: …, ! Class X Error: …입니다. 층이 올라갈수록 문구는 친절해지고, 내려갈수록 TeX이 실제로 막힌 지점에 가까워집니다. 접두사 없는 메시지가 나오면 대개 원고의 문법 자체가 망가진 것입니다.
| 줄의 모양 | 발신자와 빌드에 미치는 영향 |
|---|---|
! Missing $ inserted. | TeX 엔진 본체. 접두사가 없는 것이 표시이며 원고 문법이 깨진 상태 |
! LaTeX Error: ... | LaTeX 커널. 환경・참조・프리앰블에 관한 LaTeX 자체 규칙 위반 |
! Package X Error: ... | 이름이 적힌 패키지 X. texdoc X로 그 설명서를 읽는 것이 대개 가장 빠른 다음 수순 |
! Class X Error: ... | 문서 클래스 X. 학술지 클래스에서는 투고 규정 위반 통지인 경우가 많음 |
LaTeX Warning: ... | 커널 경고. 빌드는 성공하고 종료 코드도 0 그대로여서 낡은 참조가 살아남는 통로 |
Package X Warning: ... | 패키지 경고. on input line N이 붙는 것과 일부러 붙이지 않는 것이 있음 |
Overfull \hbox (...) | 문단 조판기에서 직접. !도 Warning도 붙지 않는 제3의 형식 |
Package X Info: ... | 정보일 뿐. 터미널에는 나오지 않고 .log에만 남지만 뒤에 생길 실패의 단서가 됨 |
TeX 엔진의 오류: 접두사가 없는 메시지
이 무리는 “TeX이 입력을 더 읽어 나갈 수 없다”는 보고이며, 원인은 거의 예외 없이 중괄호・$・&의 짝과 숫자 표기입니다. 문구가 무뚝뚝한 것은 LaTeX이 존재하기 전에 쓰인 그대로이기 때문입니다. 뒤집어 말하면, 이 문자열들은 어느 배포판에서도 어느 시대의 문서에서도 동일해 검색이 잘 됩니다. 아래 문면은 TeX Live 2024에서 실제로 재현한 것입니다.
| 메시지 | 실제 의미와 첫 수 |
|---|---|
! Undefined control sequence. | 윗줄 오른쪽 끝의 명령이 정의되지 않음. 오타, 패키지 누락, 늦은 정의 중 하나 |
! Missing $ inserted. | 수식 전용 기호를 본문에서 사용. _, ^, \alpha가 흔한 방아쇠 |
! Missing } inserted. | {가 열린 채로 무언가가 끝남. 원인은 보고된 위치보다 위쪽 |
! Too many }'s. | }가 남음. 대개 앞선 줄에서 {를 하나 빠뜨린 경우 |
! Extra alignment tab has been changed to \cr. | 표의 한 행에 &가 열 지정보다 많음. 열 정의와 개수를 맞춰 볼 것 |
! Misplaced alignment tab character &. | 표 밖에서 &를 사용. 문자 자체는 \& |
! Double subscript. | x_1_2처럼 _가 중복. x_{12}처럼 중괄호로 묶을 것 |
! Missing number, treated as zero. | 길이나 개수를 기대한 자리에 숫자가 없음. \hspace{} 같은 빈 인수가 전형 |
! Illegal unit of measure (pt inserted). | 숫자에 단위가 없음. \rule{1}{2pt}처럼 cm, pt, em을 빠뜨린 경우 |
! Paragraph ended before \x was complete. | 인수 도중에 빈 줄이 들어감. 바로 위의 Runaway argument?가 단서 |
! File ended while scanning use of \x. | 인수가 닫히지 않은 채 파일이 끝남. } 누락의 마지막 단계 |
! Missing \endcsname inserted. | \csname … \endcsname 안에 전개할 수 없는 것이 들어감. 조립한 매크로 이름을 의심할 것 |
! TeX capacity exceeded, sorry [...] | 대괄호 안이 고갈된 자원 이름. [grouping levels=255]라면 무한 재귀를 의심 |
! Emergency stop. | 대화가 불가능한 상황에서 입력을 요구받음. 비대화형 모드에서 파일이 없을 때의 전형 |
LaTeX 커널의 오류: ! LaTeX Error:로 시작하는 것들
이쪽은 TeX의 문법이 아니라 LaTeX의 규약을 어긴 경우로, 문구가 훨씬 구체적인 만큼 고치는 방법도 하나로 정해지는 일이 많습니다. 환경의 짝, \usepackage의 위치, 프리앰블 전용 명령, 존재하지 않는 파일——모두 LaTeX이 스스로 정한 규칙입니다. 또한 .log에는 이 메시지들 뒤에 도움말 문단이 이어지며 터미널의 한 줄보다 구체적이므로, 뜻이 잡히지 않으면 로그를 여십시오.
| 메시지 | 실제 의미와 첫 수 |
|---|---|
! LaTeX Error: File `x.sty' not found. | 패키지가 설치되지 않았거나 철자가 틀림. kpsewhich x.sty로 확인하고 tlmgr install x로 설치 |
! LaTeX Error: Environment x undefined. | 그 환경을 정의하는 패키지를 불러오지 않음. 환경 이름의 철자도 함께 확인 |
! LaTeX Error: \begin{x} on input line N ended by \end{y}. | 환경이 중첩이 아니라 교차함. N은 연 쪽의 행이므로 거기서부터 아래를 볼 것 |
! LaTeX Error: Command \x already defined. | 이미 있는 이름에 \newcommand를 사용. 덮어쓸 의도라면 \renewcommand를 쓸 것 |
! LaTeX Error: Missing \begin{document}. | 프리앰블에서 인쇄 가능한 것이 나옴. 공백이 아닌 한 글자만으로도 발생 |
! LaTeX Error: Option clash for package x. | 두 번째 로드가 첫 로드에 없던 옵션을 요구함. \PassOptionsToPackage로 해결 |
! LaTeX Error: Something's wrong--perhaps a missing \item. | 목록이 비었거나 첫 \item 앞에 본문이 있음 |
! LaTeX Error: There's no line here to end. | 줄이 시작되지도 않은 곳에 \\를 씀. 문단 첫머리나 center 시작 부분이 전형 |
! LaTeX Error: Not in outer par mode. | 플로트를 다른 플로트나 상자 안에 넣음. figure는 figure나 minipage 안에 들어갈 수 없음 |
! LaTeX Error: \caption outside float. | figure나 table 밖에서 \caption을 씀. 환경으로 감싸거나 \captionof를 쓸 것 |
! LaTeX Error: Can be used only in preamble. | \usepackage처럼 프리앰블 전용 명령을 본문에서 사용 |
! LaTeX Error: \usepackage before \documentclass. | \documentclass보다 앞에서 \usepackage를 사용. 그 자리에서는 \RequirePackage만 동작 |
! LaTeX Error: Unknown option `x' for package `y'. | 그 패키지가 선언하지 않은 옵션. 철자와 패키지 버전을 확인 |
! LaTeX Error: Unicode character X (U+NNNN) | 해당 문자에 정의가 없음. pdfLaTeX에서는 CJK와 이모지가 이에 해당하며 XeLaTeX・LuaLaTeX에서는 통과 |
패키지 오류: ! Package X Error:는 X의 목소리
이 층의 메시지는 이름이 적힌 패키지가 직접 쓴 문장이므로, 같은 표현이 그 패키지의 설명서에 실려 있습니다. texdoc X를 열어 메시지를 검색하는 것이 가장 짧은 길입니다. 내용도 구체적이어서 “이 환경은 여기서 쓸 수 없다”, “이 색은 정의되지 않았다”, “이 패키지와는 공존할 수 없다”처럼 대처 방법이 거의 그대로 적혀 있는 경우가 많습니다. 아래는 TeX Live 2024에서 실제로 발생시킨 것들입니다.
| 메시지 | 실제 의미와 첫 수 |
|---|---|
! Package biblatex Error: Incompatible package 'natbib'. | biblatex와 natbib은 공존 불가. \usepackage[natbib=true]{biblatex}로 대체 |
! Package cleveref Error: cleveref must be loaded after hyperref!. | 로드 순서 요구. cleveref는 hyperref 뒤, 그리고 varioref 뒤에 와야 함 |
! Package amsmath Error: \begin{split} won't work here. | split은 단독으로 쓸 수 없음. equation이나 align 안에 넣을 것 |
! Package xcolor Error: Undefined color `x'. | 색 이름이 정의되지 않음. dvipsnames 같은 색 이름 집합을 불러오거나 \definecolor로 정의 |
! Package babel Error: Unknown option 'x'. | 언어 이름의 철자가 틀렸거나 해당 언어 파일이 설치되지 않음 |
! Package pdftex.def Error: File `x.png' not found: using draft setting. | 이미지를 찾을 수 없음. 테두리만 조판하고 실행은 계속되므로 경로와 확장자를 확인 |
! Package inputenc Error: ... | TeX Live 2024에서는 거의 나오지 않음. UTF-8 처리가 커널로 옮겨져 inputenc가 할 일이 거의 없음 |
경고: 빌드를 멈추지는 않지만 방치하면 잘못된 PDF가 나갑니다
경고는 빌드를 멈추지 않고 종료 코드도 0 그대로여서 CI는 “성공”으로 판정합니다. 바로 그 점이 위험합니다. 참조가 ??인 채로 나온 PDF, 번호가 한 판 뒤처진 PDF는 여기서 태어납니다. 특히 LaTeX Warning: There were undefined references.와 Label(s) may have changed. Rerun to get cross-references right. 두 줄은 “다시 컴파일하라”는 지시이지 참고 넘길 경고가 아닙니다. 빌드 스크립트를 쓴다면 이 두 줄을 감지해 다시 돌리거나, 아예 latexmk에 맡기는 것이 정석입니다.
| 메시지 | 실제 의미와 첫 수 |
|---|---|
Overfull \hbox (12.3pt too wide) in paragraph at lines 4--5 | 줄이 판면을 넘어감. 괄호 안 숫자가 넘친 양이며 1pt 미만이면 신경 쓰지 않아도 됨 |
Underfull \hbox (badness 10000) in paragraph at lines 4--5 | 줄이 지나치게 늘어남. badness 10000이 최악값이며 불필요한 \linebreak나 \\가 흔한 원인 |
Overfull \vbox (26.3pt too high) detected at line 4 | 넘침이 세로 방향. 어떤 상자가 페이지에 들어가지 못했다는 뜻 |
LaTeX Warning: Reference `x' on page 1 undefined on input line 3. | 그 라벨이 아직 .aux에 없음. 첫 실행이거나 \label의 철자가 틀림 |
LaTeX Warning: Citation `x' on page 1 undefined on input line 3. | bibtex나 biber를 아직 돌리지 않았거나, 그 키가 .bib에 없음 |
LaTeX Warning: Label `x' multiply defined. | 같은 라벨이 두 군데 존재. 그 \ref는 둘 중 하나만 가리킬 수 있음 |
LaTeX Warning: There were undefined references. | 실행 끝의 요약. 이 줄이 남은 채 배포하면 PDF에 ??가 남음 |
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. | 번호가 지난번과 어긋남. 한 번 더 컴파일하면 사라짐 |
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined | 굵게와 작은 대문자 같은 조합이 없음. 대체 글꼴이 쓰이므로 겉모습만 달라짐 |
Package hyperref Warning: Token not allowed in a PDF string (Unicode): | 제목 속 수식은 PDF 책갈피에 들어갈 수 없음. \texorpdfstring{수식}{일반}으로 나눌 것 |
이제 나오지 않는 메시지: 오래된 정보에만 남아 있는 것들
검색으로 찾은 오래된 답변에는 TeX Live 2024에서 더 이상 나오지 않는 메시지가 섞여 있습니다. 같은 문자열이 보이지 않는다고 해서 내 환경이 망가진 것은 아닙니다. 가장 뚜렷한 예가 유니코드 문자 오류입니다. 예전에는 ! Package inputenc Error: Unicode character …였지만, UTF-8 처리가 커널로 옮겨 간 지금은 ! LaTeX Error: Unicode character 日 (U+65E5)이고 다음 줄에 not set up for use with LaTeX.가 이어집니다. 게다가 →와 €는 이제 아예 오류가 나지 않습니다. 측정해 보면 문자는 pdfLaTeX이 받아들이게 된 쪽과, CJK・이모지・≤처럼 여전히 거부하는 쪽으로 갈립니다. xcolor의 옵션 충돌도 같은 이유로 과거의 일이 되었습니다(자세한 내용은 “패키지 충돌” 페이지).
- 유니코드 문자 — 메시지가
! Package inputenc Error:가 아니라! LaTeX Error: Unicode character 日 (U+65E5)로 바뀌었습니다. pdfLaTeX에서→와€는 통과하고 CJK・이모지・≤는 여전히 통과하지 못합니다. xcolor의 옵션 충돌 —\usepackage[dvipsnames]{xcolor}다음에\usepackage[table]{xcolor}를 써도 오류가 전혀 나지 않습니다. xcolor가 키-값 방식 옵션으로 옮겨 갔기 때문입니다.caption과subfigure— 예전의 “함께 쓸 수 없다”는 오류는 사라졌고, 지금은.log에Package caption Info: subfigure package is loaded.가 기록될 뿐입니다.subfigure와subcaption— 둘을 함께 불러도 오류가 나지 않습니다. 대신\begin{subfigure}가 옛\subfigure명령에 먹혀,! Missing number, treated as zero.처럼 무관해 보이는 오류가 납니다.