가이드

자주 발생하는 YAML 오류

거의 모든 파싱 실패는 여섯 가지 실수에서 비롯됩니다. 각각의 의미와 정확한 해결 방법입니다.

작성 yamltojsonfree · 게시일 2026년 8월 25일 · 수정일 2026년 9월 1일

YAML 오류가 읽기 어려운 이유

YAML은 들여쓰기로 구조를 만들기 때문에, 무언가 잘못되면 파서는 무엇이 잘못되었는지 알지 못하는 경우가 많습니다 — 구조가 더 이상 말이 되지 않는다는 것만 압니다. 그래서 12번째 줄의 닫히지 않은 괄호가 50번째 줄의 "잘못된 들여쓰기"로 보고되는 일이 흔합니다. 파서는 오지 않을 닫는 구분자를 찾으며 줄을 계속 읽다가 한참 뒤에야 포기합니다.

아래 오류는 파서가 출력하는 메시지가 아니라 진짜 원인에 따라 나열했습니다. 자동으로 진단받고 싶다면 문서를 YAML 검증기나 YAML → JSON 변환기에 붙여넣으세요 — 이 오류들은 각각 본래 모습대로 감지되며, 줄과 쉬운 설명과 제안된 해결책이 함께 제공됩니다.

여섯 가지 오류 상세

가장 흔한 여섯 가지 YAML 문법 오류는 다음과 같습니다: (1) 들여쓰기에 사용된 탭, (2) 콜론이 포함된 따옴표 없는 값, (3) 닫히지 않은 대괄호·중괄호·따옴표, (4) 중복 키, (5) 존재하지 않는 앵커를 가리키는 별칭, (6) 서로 다르게 들여쓴 형제 키.

1. 들여쓰기에 탭 문자가 사용됨

원인: 탭의 너비는 편집기마다 모호하기 때문에 YAML은 들여쓰기에 탭을 완전히 금지합니다.

해결: 모든 탭을 공백으로 바꾸세요 — 단계당 2칸이 관례입니다. 대부분의 편집기는 "들여쓰기를 공백으로 변환"으로 이를 처리할 수 있습니다.

2. 따옴표 없는 값에 콜론이 포함됨

원인: title: foo: bar는 모호합니다 — 파서는 어느 콜론이 키와 값을 구분하는지 알 수 없습니다.

해결: 값을 따옴표로 감싸세요: title: 'foo: bar'.

3. 대괄호, 중괄호, 따옴표가 닫히지 않음

원인: [80, 443] 같은 플로우 컬렉션과 따옴표 문자열은 같은 논리적 줄에서 닫혀야 합니다. 대부분의 파서는 이를 여러 줄 뒤에서 들여쓰기 오류로 보고합니다.

해결: 닫는 구분자를 추가하거나, 값을 한 줄에 한 항목씩 블록 스타일로 다시 쓰세요.

4. 같은 키가 두 번 나타남

원인: YAML 매핑은 고유한 키를 요구하며 JSON 객체도 마찬가지입니다. 마지막 값을 조용히 채택하면 진짜 버그가 숨겨집니다.

해결: 중복을 이름 바꾸거나 제거하세요 — 하위 키로 의도했다면 한 단계 더 들여쓰세요.

5. 별칭이 존재하지 않는 앵커를 가리킴

원인: *name은 &name으로 정의된 앵커를 참조합니다. 앵커는 그것을 사용하는 별칭보다 문서에서 먼저 나와야 합니다.

해결: 앵커를 먼저 정의하고 철자를 확인하세요 — 앵커 이름은 대소문자를 구분합니다.

6. 형제 키의 들여쓰기가 다름

원인: 같은 블록의 모든 키는 같은 들여쓰기에 있어야 합니다. 한 줄은 2칸, 다음 줄은 3칸이면 블록이 일찍 끝납니다.

해결: 모든 형제 키의 들여쓰기를 동일하게 맞추세요.

두 가지 수정 예시, 전과 후

사람들이 가장 자주 마주치는 두 가지 오류를, 깨진 YAML과 수정된 형태를 나란히 보여 줍니다.

값 안의 따옴표 없는 콜론

두 번째 콜론이 줄을 모호하게 만듭니다. 값 전체를 따옴표로 감싸면 해결됩니다.

오류

title: Deploy: production
owner: platform team

수정됨

title: "Deploy: production"
owner: platform team

고르지 않은 형제 들여쓰기

"ports"는 3칸이고 형제들은 2칸이라 블록이 일찍 끝납니다.

오류

server:
  host: localhost
   ports:
    - 8080

수정됨

server:
  host: localhost
  ports:
    - 8080

YAML은 유효한데 여전히 잘못되었을 때

문서는 완벽하게 파싱되면서도 의도와 다른 의미를 가질 수 있습니다. 전형적인 예가 country: NO로, 모든 버전에서 유효한 YAML입니다 — 하지만 YAML 1.2에서는 문자열 "NO", YAML 1.1에서는 불리언 false로 읽힙니다. 이런 조용한 타입 변화 전체는 YAML 1.1과 1.2 차이 가이드에서 다룹니다.

참고 자료

YAML 1.2.2 명세 — 들여쓰기, 플로우 컬렉션, 앵커, 고유 키 규칙
YAML 1.2.2 §6.1 들여쓰기 공백 — 탭이 허용되지 않는 이유
PyYAML 문서 — 대부분의 Python 사용자가 보는 오류 메시지
js-yaml — 이 사이트 도구 뒤의 파서

지금 YAML 고치기

이 페이지의 모든 오류는 이 사이트의 무료 도구가 정확한 줄과 제안된 해결책과 함께 잡아냅니다. 어떤 것도 업로드되지 않으며 모든 것은 브라우저에서 실행됩니다.

YAML 1.1과 1.2

country: NO가 false가 될 수 있는 이유와 안전한 YAML 작성법.

가이드 읽기

코드에서 YAML을 JSON으로 변환

Python, Node.js, Go, yq 예제로 반복 변환하기.