Cara Debug Kesalahan YAML: Indentasi, Tab, dan Error Umum Lainnya
YAML terkenal sensitif — beda satu spasi saja bisa bikin file gagal di-parse, atau lebih parah, berhasil di-parse tapi menghasilkan struktur data yang salah tanpa error sama sekali. Ini bikin debugging YAML kadang terasa lebih susah dibanding JSON, karena pesan error dari parser tidak selalu jelas menunjukkan akar masalahnya. Artikel ini merangkum kesalahan paling umum di YAML dan cara sistematis menemukannya, supaya kamu tidak perlu menghabiskan berjam-jam menebak-nebak baris mana yang sebenarnya bermasalah.
1. Mencampur Tab dan Spasi
Ini kesalahan paling klasik dan paling sering bikin frustrasi pemula. Spesifikasi YAML melarang penggunaan karakter tab untuk indentasi — harus selalu pakai spasi. Kalau editor kamu diam-diam menyisipkan tab (sering terjadi kalau kamu copy-paste dari sumber lain atau editor dengan setting auto-indent yang salah), parser akan melempar error yang kadang membingungkan seperti "found character that cannot start any token". Masalahnya, karakter tab dan spasi terlihat identik secara visual di kebanyakan editor default, jadi kamu bisa menatap baris yang "kelihatan benar" selama beberapa menit sebelum sadar masalahnya ada di whitespace yang tidak terlihat:
# Ini akan error kalau ada tab tersembunyi sebelum "name"
person:
name: Sarah AmeliaCara debug: aktifkan opsi "show whitespace" atau "render whitespace" di editor kamu (tersedia di VS Code, Sublime Text, dll) supaya tab dan spasi terlihat berbeda secara visual. Banyak editor modern juga bisa dikonfigurasi untuk otomatis convert tab jadi spasi saat mengetik di file .yml/.yaml.
2. Indentasi Tidak Konsisten
YAML memakai indentasi untuk menentukan hierarki, mirip Python. Masalah muncul kalau level indentasi tidak konsisten antar baris yang seharusnya sejajar:
# Salah — child kedua indentasinya beda dengan child pertama
person:
name: Sarah Amelia
age: 29Baris age di atas punya 3 spasi, sementara name punya 2 spasi — parser akan bingung apakah age itu child dari name (yang tidak masuk akal karena name value-nya string, bukan map) atau sibling. Hasilnya biasanya error parsing yang eksplisit menyebutkan baris dan kolom bermasalah.
Cara debug: pastikan editor kamu dikonfigurasi konsisten memakai jumlah spasi yang sama untuk setiap level (umumnya 2 spasi per level). Gunakan linter YAML (seperti yamllint) yang bisa mendeteksi inkonsistensi indentasi secara otomatis sebelum file dijalankan.
3. String yang Perlu Di-quote Tapi Tidak Di-quote
YAML punya banyak aturan implisit soal kapan sebuah nilai dianggap string vs tipe lain, dan ini sering jadi sumber bug yang tidak menghasilkan error sama sekali — cuma hasil parsing yang salah:
config:
version: 1.10 # jadi number 1.1, BUKAN string "1.10" — trailing zero hilang!
enabled: yes # jadi boolean true, bukan string "yes"
port: "8080" # ini string kalau di-quote, number kalau tidak
country: NO # jadi boolean false! (YAML 1.1 menganggap NO/YES/ON/OFF sebagai boolean)Kasus country: NO adalah salah satu bug paling terkenal di komunitas YAML — kode negara Norwegia (NO) tanpa sengaja jadi false di banyak parser YAML 1.1. Ini sering disebut "Norway Problem".
Cara debug: selalu quote string yang berisi angka, boolean-like word (yes/no/true/false/on/off), atau karakter spesial, terutama untuk value yang secara semantik memang harus string (kode negara, versi, nomor telepon):
config:
version: "1.10"
enabled: true
country: "NO"4. Colon Tanpa Spasi Setelahnya
YAML butuh spasi setelah colon : untuk membedakan key-value dari string biasa yang kebetulan mengandung colon:
# Salah — ditafsirkan sebagai satu string, bukan key-value
url:http://example.com
# Benar
url: http://example.comKasus lain yang sering bikin bingung: value yang mengandung colon di tengah tanpa di-quote:
# Bisa error atau salah parsing tergantung parser
time: 10:30:00
# Aman — di-quote
time: "10:30:00"5. Multi-line String yang Salah Pakai | atau >
YAML punya dua cara menulis string multi-baris, dan sering tertukar:
description_literal: |
Baris pertama.
Baris kedua.
description_folded: >
Baris pertama.
Baris kedua.| (literal block) mempertahankan line break apa adanya — hasilnya "Baris pertama.\nBaris kedua.\n". > (folded block) menggabungkan baris jadi satu paragraf dengan spasi — hasilnya "Baris pertama. Baris kedua.\n". Salah pilih di antara keduanya adalah sumber bug umum ketika output yang diharapkan multi-baris tapi malah jadi satu baris panjang, atau sebaliknya.
6. List Item Kurang Indentasi Relatif ke Parent Key
# Ambigu di beberapa parser — dash sejajar dengan key
fruits:
- apple
- banana
# Lebih aman — dash diindentasi
fruits:
- apple
- bananaYAML sebenarnya membolehkan dash sejajar dengan parent key (kasus pertama valid secara spec), tapi ini bisa membingungkan secara visual dan beberapa tool/linter lebih strict soal ini. Untuk konsistensi dan keterbacaan, sebaiknya selalu indentasi list item.
Strategi Debugging Sistematis
Kalau langkah-langkah dasar di atas belum menemukan akar masalah, coba pendekatan yang lebih sistematis berikut ini:
- Baca pesan error dengan teliti — kebanyakan parser YAML menyebutkan nomor baris dan kolom tempat masalah terdeteksi. Meski kadang lokasi sebenarnya sedikit berbeda dari yang dilaporkan (karena parser baru "sadar" ada masalah beberapa token kemudian), ini titik awal yang baik.
- Isolasi bagian yang error — kalau file besar, coba comment-out atau hapus sementara bagian-bagian untuk mempersempit lokasi masalah lewat binary search manual.
- Gunakan validator/formatter online — tool yang memformat ulang YAML kamu bisa membantu mengungkap masalah struktural yang tidak kelihatan jelas di editor biasa.
- Konversi ke JSON untuk verifikasi — kalau kamu ragu apakah YAML sudah menghasilkan struktur data yang benar, konversi ke JSON dan periksa hasilnya secara visual; JSON lebih eksplisit soal tipe data dan strukturnya, jadi lebih mudah melihat kesalahan seperti "yes" yang ternyata jadi boolean.
- Pakai linter di CI/CD — integrasikan
yamllintatau tool serupa ke pipeline supaya kesalahan format terdeteksi otomatis sebelum merge, bukan ditemukan manual saat sudah deploy. Konfigurasi linter juga bisa disesuaikan tim untuk memberlakukan aturan tambahan, seperti melarang trailing whitespace atau mewajibkan document start marker---, sehingga standar penulisan YAML tetap konsisten meskipun ditulis oleh banyak orang berbeda.
How to Debug YAML Errors: Indentation, Tabs, and Other Common Issues
YAML is notoriously sensitive — being off by a single space can make a file fail to parse, or worse, parse successfully but produce the wrong data structure with no error at all. This makes debugging YAML sometimes feel harder than JSON, since parser error messages don't always clearly point to the root cause. This article rounds up the most common YAML mistakes and a systematic way to find them.
1. Mixing Tabs and Spaces
This is the most classic and most frustrating beginner mistake. The YAML spec forbids using tab characters for indentation — you must always use spaces. If your editor silently inserts a tab (often happens when copy-pasting from another source, or with an editor that has a broken auto-indent setting), the parser will throw a sometimes-confusing error like "found character that cannot start any token":
# This will error if there's a hidden tab before "name"
person:
name: Sarah AmeliaHow to debug: turn on "show whitespace" or "render whitespace" in your editor (available in VS Code, Sublime Text, etc.) so tabs and spaces look visually different. Many modern editors can also be configured to automatically convert tabs to spaces when typing in a .yml/.yaml file.
2. Inconsistent Indentation
YAML uses indentation to determine hierarchy, similar to Python. Problems arise when the indentation level isn't consistent between lines that should be siblings:
# Wrong — second child's indentation differs from the first
person:
name: Sarah Amelia
age: 29The age line above has 3 spaces, while name has 2 — the parser gets confused whether age is a child of name (which doesn't make sense since name's value is a string, not a map) or a sibling. This usually results in a parsing error that explicitly points at the problematic line and column.
How to debug: make sure your editor is configured to consistently use the same number of spaces per level (usually 2 spaces per level). Use a YAML linter (like yamllint) that can automatically detect indentation inconsistencies before the file is run.
3. Strings That Need Quoting But Aren't Quoted
YAML has many implicit rules about when a value is treated as a string vs another type, and this is often a source of bugs that produce no error at all — just an incorrectly parsed result:
config:
version: 1.10 # becomes the number 1.1, NOT the string "1.10" — trailing zero lost!
enabled: yes # becomes boolean true, not the string "yes"
port: "8080" # this stays a string if quoted, a number if not
country: NO # becomes boolean false! (YAML 1.1 treats NO/YES/ON/OFF as booleans)The country: NO case is one of the most infamous bugs in the YAML community — Norway's country code (NO) accidentally becomes false in many YAML 1.1 parsers. This is often called the "Norway Problem."
How to debug: always quote strings that contain numbers, boolean-like words (yes/no/true/false/on/off), or special characters, especially for values that are semantically meant to be strings (country codes, version numbers, phone numbers):
config:
version: "1.10"
enabled: true
country: "NO"4. A Colon Without a Space After It
YAML needs a space after a colon : to distinguish a key-value pair from a plain string that happens to contain a colon:
# Wrong — interpreted as a single string, not a key-value pair
url:http://example.com
# Correct
url: http://example.comAnother confusing case: a value containing a colon in the middle without being quoted:
# May error or parse incorrectly depending on the parser
time: 10:30:00
# Safe — quoted
time: "10:30:00"5. Multi-line Strings Using | or > Incorrectly
YAML has two ways to write multi-line strings, and they're often mixed up:
description_literal: |
First line.
Second line.
description_folded: >
First line.
Second line.| (literal block) preserves line breaks as-is — the result is "First line.\nSecond line.\n". > (folded block) joins lines into a single paragraph with spaces — the result is "First line. Second line.\n". Picking the wrong one is a common source of bugs where output expected to be multi-line ends up as one long line, or vice versa.
6. List Items Under-Indented Relative to the Parent Key
# Ambiguous in some parsers — dash aligned with key
fruits:
- apple
- banana
# Safer — dash indented
fruits:
- apple
- bananaYAML actually allows the dash to align with the parent key (the first case is valid per spec), but it can be visually confusing and some tools/linters are stricter about it. For consistency and readability, it's best to always indent list items.
A Systematic Debugging Strategy
- Read the error message carefully — most YAML parsers report the line and column where the problem was detected. Even though the actual location might be slightly off from what's reported (since the parser only "realizes" there's a problem a few tokens later), it's a good starting point.
- Isolate the failing section — for large files, try commenting out or temporarily removing sections to narrow down the problem location via manual binary search.
- Use an online validator/formatter — a tool that reformats your YAML can help surface structural problems that aren't obvious in a plain editor.
- Convert to JSON to verify — if you're unsure whether your YAML produces the correct data structure, convert it to JSON and inspect the result visually; JSON is more explicit about data types and structure, making it easier to spot mistakes like "yes" secretly becoming a boolean.
- Run a linter in CI/CD — integrate
yamllintor a similar tool into your pipeline so formatting mistakes are caught automatically before merge, rather than discovered manually after deployment.