T
yaml debugging configuration web-development devops

'YAML parse error' 및 일반적인 YAML 들여쓰기 문제 해결 방법

'invalid YAML', 'YAML indentation error', 'YAML tab character' 문제를 해결하기 위한 종합 가이드입니다. YAML 구문의 엄격한 규칙을 알아보세요.

2026-04-11

"YAML parse error" 및 일반적인 YAML 들여쓰기 문제 해결 방법: 완벽 가이드

YAML (YAML Ain't Markup Language)은 사람이 읽기 쉬운 형식과 깔끔한 구문 덕분에 많은 사랑을 받고 있습니다. Kubernetes, Docker Compose, GitHub Actions 및 수많은 정적 사이트 생성기에서 설정 파일의 표준으로 사용됩니다. 하지만 YAML은 공백과 들여쓰기에 매우 엄격한 것으로 유명합니다. 단 하나의 잘못된 공백만으로도 추적하기 어려운 invalid YAML이나 YAML parse error가 발생할 수 있습니다.

이 가이드에서는 가장 흔한 YAML 오류와 이를 빠르게 수정하는 방법을 살펴보겠습니다.

1. 일반적인 YAML 오류 메시지

사용 중인 파서(js-yaml 또는 Python의 PyYAML 등)에 따라 다음과 같은 메시지가 나타날 수 있습니다.

  • YAML parse error: bad indentation of a mapping entry (매핑 항목의 잘못된 들여쓰기)
  • YAML parse error: found character '\t' that cannot start any token (YAML tab character 포함 오류)
  • invalid YAML: mapping values are not allowed here (여기서는 매핑 값을 사용할 수 없음)
  • YAML parse error: duplicate key "..." (duplicate key in YAML / 중복된 키 오류)
  • YAML syntax error: end of stream loss

2. 주요 원인 및 해결 방법

2.1 들여쓰기 오류 (YAML indentation error)

YAML은 구조를 정의하기 위해 들여쓰기를 사용합니다(JSON의 중괄호 {}와 유사함). 들여쓰기는 반드시 일관성이 있어야 합니다.

자주 하는 실수:

services:
  web:
    image: nginx
   ports:  # 잘못된 들여쓰기 (2개 또는 4개가 아닌 3개의 공백)
      - "80:80"

해결 방법: 맵이나 리스트의 모든 형제 항목이 정확히 동일한 수의 선행 공백을 가지고 있는지 확인하세요. 업계 표준으로 2개의 공백을 사용하는 것이 좋습니다.

2.2 탭 문자 (YAML tab character)

YAML은 들여쓰기에 탭 문자(\t)를 사용하는 것을 엄격히 금지합니다. 반드시 공백(Space)을 사용해야 합니다.

오류 현상: found character '\t' that cannot start any token

해결 방법: 코드 에디터(VS Code, Sublime 등) 설정에서 "탭을 공백으로 변환" 기능을 활성화하세요. 이미 탭이 포함된 코드를 붙여넣었다면 '찾기 및 바꾸기'를 사용하여 \t를 로 변경하세요.

2.3 중복된 키 (duplicate key in YAML)

다른 형식과 달리 YAML은 매핑의 동일한 수준에서 동일한 키가 두 번 나타나는 것을 허용하지 않습니다.

자주 하는 실수:

image: nginx
ports:
  - "80:80"
image: alpine  # 중복된 키!

해결 방법: 특히 파일이 크거나 여러 파일을 병합할 때 실수로 키가 중복되지 않았는지 설정을 확인하세요.

2.4 콜론 뒤 공백 누락

YAML에서 흔히 저지르는 실수 중 하나는 키와 값을 구분하는 콜론(:) 뒤에 공백을 넣는 것을 잊는 것입니다.

자주 하는 실수: url:https://example.com (YAML은 이를 하나의 긴 문자열로 인식합니다)

해결 방법: 항상 공백을 포함하세요: url: https://example.com.

2.5 여러 줄 문자열

긴 문자열이나 코드 블록을 포함해야 하는 경우 올바른 블록 스칼라 표시자를 사용해야 합니다. | (줄바꿈 유지) 또는 > (줄바꿈 접기)를 사용하세요.

자주 하는 실수:

description: This is a
very long string
without indicators. # 이 경우 구문 분석 오류가 발생합니다.

해결 방법:

description: |
  이것은 줄바꿈을
  유지하는 매우
  긴 문자열입니다.

3. 고급 문제 해결

3.1 값 내부의 특수 문자

값에 :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `와 같은 문자가 포함되어 있으면 파서가 혼동을 일으킬 수 있습니다. 해결 방법: 값 전체를 큰따옴표("...") 또는 작은따옴표('...')로 감싸세요.

3.2 불리언(Boolean) 관련 주의사항

YAML 1.1에서는 yes, no, on, off와 같은 값이 자동으로 불리언(true/false)으로 변환됩니다. 국가 코드와 같이 문자열 "no"가 필요한 경우 문제가 될 수 있습니다. 해결 방법: 이러한 문자열은 항상 따옴표를 사용하세요: country: "NO".

4. 예방 및 권장 사항

  1. YAML Linter 사용: 에디터에 Linter(예: Red Hat의 vscode-yaml)를 설치하여 실시간으로 오류를 파악하세요.
  2. 스키마 검증: Kubernetes나 Docker Compose와 같은 특정 형식의 경우 공식 JSON/YAML 스키마를 사용하여 유효성을 검사하세요.
  3. 자동 변환: JSON이 더 편하다면 설정을 JSON으로 작성한 후 도구를 사용하여 YAML로 변환하세요.
  4. 일관된 간격: 프로젝트의 모든 YAML 파일에 대해 공백 2개 사용을 표준화하세요.

5. 자주 묻는 질문 FAQ

Q: 한 파서에서는 유효한데 다른 파서에서는 왜 오류가 나나요?

A: YAML에는 주로 1.1과 1.2라는 두 가지 버전이 있습니다. 일부 파서(PyYAML 등)는 기본적으로 1.1을 사용하고, 다른 파서는 1.2를 사용합니다. 버전 1.2는 JSON과 더 호환됩니다. 문제가 발생하면 파일 상단에 %YAML 1.2를 추가해 보세요.

Q: YAML에서 주석을 사용할 수 있나요?

A: 네! 이는 YAML이 JSON에 비해 갖는 큰 장점 중 하나입니다. # 기호를 사용하여 주석을 작성하세요.

Q: 작은따옴표로 감싸인 문자열 안에서 작은따옴표를 어떻게 이스케이프하나요?

A: YAML에서는 작은따옴표를 두 번 써서 이스케이프합니다: 'It''s a beautiful day'.

6. 빠른 확인 도구

보이지 않는 탭 문자나 잘못된 공백을 찾는 데 어려움을 겪고 계신가요? 저희의 YAML 유효성 검사 및 포맷터 (YAML-to-JSON 변환 및 검증 지원)를 사용해 보세요.

  • 구문 오류를 하이라이트하고 줄 번호를 표시합니다.
  • 탭을 공백으로 자동으로 변환합니다.
  • 복잡한 YAML을 보기 좋게 정리하여 가독성을 높입니다.

관련 오류

  • JSON의 'Unexpected token' 오류 해결 방법
  • 'invalid base64 string' 오류 수정 방법
  • 문자 인코딩 불일치 이해하기
블로그로 돌아가기