Cara Mendeteksi dan Memperbaiki Kesalahan YAML: Sintaks, Indentasi, dan Validasi

YAML memperoleh seluruh strukturnya dari whitespace. Tidak ada kurung siku, tidak ada kurung kurawal, tidak ada pembatas blok eksplisit — hanya tingkat indentasi dan titik dua. Ini membuat YAML sangat mudah dibaca ketika benar dan sangat menyebalkan ketika salah, karena karakter yang sama yang mengorganisir data Anda dapat menghancurkannya secara diam-diam jika bergeser satu kolom.

Parser melaporkan di mana ia menyerah, bukan di mana Anda membuat kesalahan

Kesulitan utama pesan kesalahan YAML adalah parser melaporkan baris di mana mereka berhenti dapat menafsirkan dokumen — bukan baris di mana kesalahan aslinya dibuat. Titik dua yang hilang di baris 15 mungkin tidak muncul sebagai kesalahan sampai baris 22, ketika kunci berikutnya datang dalam konteks yang tak terduga. Artinya, Anda hampir selalu perlu melihat beberapa baris di atas kesalahan yang dilaporkan untuk menemukan penyebab sebenarnya.

• Kesalahan indentasi menjalar berantai — blok induk yang salah indentasi membuat setiap kunci anak melaporkan kesalahan
• Karakter tab tampak identik dengan spasi tetapi memicu kegagalan parsing di parser mana pun yang sesuai spesifikasi
• Kunci duplikat lolos pemeriksaan sintaks dasar secara diam-diam — satu nilai ditimpa tanpa peringatan apa pun
• Karakter khusus tanpa tanda kutip seperti :, #, *, dan & mengubah makna dokumen secara tak terduga
• Anchor dan alias gagal diam-diam jika sebuah alias merujuk ke anchor yang tidak ada dalam berkas yang sama

Versi YAML itu penting

Sebagian besar alat modern menarget YAML 1.2, yang mengetatkan beberapa aturan parsing yang diizinkan YAML 1.1. Misalnya, YAML 1.1 memperlakukan yes, no, on, dan off sebagai nilai boolean; YAML 1.2 tidak. Jika konfigurasi Anda menggunakan string telanjang ini dan validator Anda melaporkan konversi tipe yang tak terduga, ketidakcocokan versi YAML adalah penyebabnya. Selalu periksa versi spesifikasi mana yang diimplementasikan parser runtime Anda.

Kesalahan YAML jatuh ke dalam sejumlah kecil kategori yang berulang. Mengenali kategori dari pesan kesalahan — atau dari tampilan visual berkas — memangkas waktu diagnosis dari menit menjadi detik.

Kesalahan indentasi

YAML menuntut indentasi yang konsisten. Spesifikasi tidak mewajibkan jumlah spasi tertentu, tetapi setiap tingkat harus menjorok lebih dalam dari induknya sebesar jumlah yang sama di dalam blok tersebut. Mencampur indentasi dua dan empat spasi dalam berkas yang sama, atau menjorokkan item sekuens satu spasi lebih sedikit dari pasangannya, akan menghasilkan kesalahan "indentasi tak terduga" atau "entri blok yang diharapkan tidak ditemukan". Praktik teraman adalah dua spasi per tingkat di seluruh berkas.

Karakter tab alih-alih spasi

Spesifikasi YAML secara eksplisit melarang karakter tab sebagai indentasi. Sebagian besar parser melempar kesalahan "menemukan karakter yang tidak dapat memulai token apa pun" atau "karakter tab ada di awal baris" saat menemukannya. Masalah ini tak terlihat di sebagian besar editor kecuali Anda mengaktifkan opsi "tampilkan whitespace" atau "render whitespace". Atur editor Anda untuk selalu memperluas tab menjadi spasi untuk berkas .yaml dan .yml guna menghilangkan kategori ini sepenuhnya.

String tanpa tanda kutip dengan karakter khusus

YAML mencadangkan beberapa karakter untuk tujuan struktural: titik dua, pagar, asterisk, ampersand, tanda seru, pipe, tanda lebih dari, kurung siku, dan kurung kurawal. Ketika salah satu karakter ini muncul dalam nilai string tanpa tanda kutip, parser dapat salah menafsirkannya sebagai token sintaks. Manifestasi paling umum adalah nilai URL seperti https://example.com:8080 yang memicu kesalahan "mapping values are not allowed here" karena :8080 diparse sebagai kunci mapping baru. Beri tanda kutip pada setiap nilai string yang memuat karakter-karakter ini.

Pesan kesalahan YAML terkenal sangat singkat. Memahami cara memecahkan dua atau tiga informasi yang benar-benar diberikan menghemat waktu debugging yang signifikan. Setiap pesan parser memuat referensi baris dan kolom, deskripsi apa yang diharapkan, dan terkadang deskripsi apa yang ditemukan sebagai gantinya.

Kesalahan pada baris 30 kolom 1 biasanya berarti masalahnya dimulai di baris 20. Baca ke atas.

Tiga bagian kesalahan parser

• Baris dan kolom: menunjuk ke tempat parsing gagal, tidak selalu tempat kesalahannya — lihat 5–10 baris di atas
• Token yang diharapkan: apa yang dicari parser — "diharapkan nilai mapping" berarti ia mengharapkan titik dua setelah kunci
• Token yang ditemukan: apa yang sebenarnya ditemui parser — "ditemukan entri sekuens blok" berarti ia menabrak item daftar - di tempat ia mengharapkan kunci

Memecahkan pola pesan yang umum

"could not find expected ':'" berarti parser membaca kunci mapping tetapi mencapai akhir baris atau token bukan titik dua sebelum menemukan pemisah. Kunci mungkin memuat karakter tercadangkan yang mengakhiri token kunci lebih awal, atau titik dua terlewat secara tak sengaja. "mapping values are not allowed here" berarti sebuah : muncul dalam konteks di mana parser tidak berada di blok mapping — biasanya disebabkan URL atau string versi tanpa tanda kutip. "found duplicate key" dimunculkan oleh parser ketat (yaml.v3 milik Go, ruamel.yaml) ketika nama kunci yang sama muncul lebih dari sekali dalam satu blok — perubahan konfigurasi di mana kunci lama tidak dihapus.

Jalur tercepat dari berkas YAML yang rusak ke yang berfungsi adalah alur kerja terstruktur yang sadar kategori, bukan pemeriksaan visual baris demi baris. Lima langkah ini mencakup setiap skenario umum.

Jenis berkas YAML yang berbeda menarik pola kesalahan yang berbeda. Mengetahui kesalahan apa yang paling umum pada setiap jenis berkas memungkinkan Anda memeriksa hal yang tepat terlebih dahulu alih-alih memindai seluruh dokumen.

Workflow GitHub Actions

Workflow GitHub Actions gagal pada tahap parsing sebelum job apa pun dieksekusi, menjadikan kesalahan YAML hal pertama yang harus diperbaiki. Kesalahan paling umum adalah on: yang diperlakukan sebagai boolean (true) karena on adalah boolean YAML 1.1 — beri tanda kutip sebagai "on" atau gunakan nama trigger lengkap. Blok run: langkah dengan skrip shell multibaris yang memakai indikator blok skalar yang salah (folded > alih-alih literal |) juga menyebabkan kesalahan senyap di mana baris baru dilipat. Gunakan | untuk skrip shell multibaris. Validator Workflow GitHub Actions memeriksa sintaks YAML dan aturan struktural khas workflow dalam satu lintasan.

Manifes Kubernetes

Kesalahan YAML Kubernetes biasanya melibatkan kesalahan indentasi bersarang yang dalam — blok containers yang diindentasi empat spasi di bawah spec padahal blok sekitarnya memakai dua, atau blok resources.limits ditempatkan pada tingkat penyusunan yang salah. Server API Kubernetes melaporkannya sebagai kesalahan validasi bidang, bukan kesalahan sintaks YAML, karena kubectl apply pertama-tama memparse YAML dengan sukses lalu memvalidasi skema objeknya. Gunakan Validator Kubernetes untuk menangkap masalah YAML dan skema sebelum diterapkan. Penyorot Diff untuk Config JSON/YAML berguna untuk membandingkan manifes antar lingkungan.

Berkas Docker Compose

Kesalahan docker-compose.yml Docker Compose paling sering berupa kesalahan indentasi pada definisi layanan, pemetaan port tanpa tanda kutip seperti 3000:3000 (titik dua memicu kesalahan parser kecuali diberi tanda kutip atau ditulis sebagai item sekuens), dan nilai variabel lingkungan yang memuat tanda sama dengan atau karakter pagar tanpa tanda kutip. Selalu beri tanda kutip pada nilai variabel lingkungan. Validator Docker Compose memvalidasi struktur YAML dan skema khusus Compose.

Berkas values.yaml Helm

Berkas values.yaml Helm sering menggunakan anchor YAML untuk konfigurasi DRY — dan kesalahan terkait anchor umum terjadi setelah restrukturisasi. Validator Values Helm memvalidasi sintaks khusus Helm, sementara Alat Diff Drift YAML Values Helm membantu membandingkan nilai antar rilis untuk menangkap drift yang ditimbulkan oleh penyuntingan baru-baru ini.

Playbook Ansible

Playbook Ansible menggabungkan YAML standar dengan ekspresi template Jinja2 yang menggunakan kurung kurawal ganda di sekitar nama variabel. Kurung kurawal ganda bukan sintaks YAML, tetapi muncul di dalam nilai string YAML. Jika ekspresi Jinja muncul sebagai keseluruhan nilai kunci tanpa tanda kutip, parser YAML Ansible memperlakukan kurung kurawal pembuka sebagai awal mapping flow. Selalu beri tanda kutip pada setiap nilai YAML yang diawali kurung kurawal ganda. Validator Ansible menangani lapisan YAML dan Jinja2 dalam validasi playbook.

Melampaui sintaks dasar, beberapa fitur YAML memiliki kategori kesalahan sendiri yang membutuhkan pendekatan diagnostik spesifik. Ini lebih jarang tetapi cenderung lebih sulit didiagnosis tanpa alat yang tepat.

Kunci duplikat — kehilangan data senyap

Kunci duplikat adalah kategori kesalahan YAML paling berbahaya karena tidak memicu kegagalan parsing di sebagian besar parser. Ketika Anda merefaktor berkas konfigurasi dan menambahkan nilai baru untuk kunci tanpa menghapus yang lama, kedua kunci hidup berdampingan di teks mentah. Tergantung parser, nilai pertama atau terakhir yang menang — PyYAML dan js-yaml sama-sama memakai kemunculan terakhir secara diam-diam, sedangkan yaml.v3 milik Go melaporkan kesalahan. Hasilnya adalah berkas konfigurasi yang tampak benar saat dibaca tetapi berperilaku berbeda saat runtime dari yang Anda harapkan.

Kesalahan anchor dan alias

Anchor YAML (&name) memungkinkan Anda mendefinisikan nilai sekali dan merujuknya di tempat lain dengan alias (*name). Kesalahan terjadi ketika alias merujuk ke anchor yang dideklarasikan belakangan dalam berkas (referensi maju tidak diizinkan dalam YAML), ketika dua anchor berbagi nama yang sama (yang kedua menimpa yang pertama secara diam-diam), atau ketika merge key (<<: *alias) dipakai pada node yang bukan mapping. Kesalahan ini tak terlihat oleh validator dasar — hanya validator yang secara khusus melacak deklarasi anchor dan rujukan alias yang akan menangkapnya.

Ketidaksesuaian substitusi variabel lingkungan

Docker Compose, GitHub Actions, dan Ansible semuanya mendukung substitusi variabel lingkungan di dalam nilai YAML. Ketika variabel lingkungan tidak diatur saat parsing, substitusi gagal, memakai string kosong, atau mundur ke nilai bawaan — tergantung sintaks yang dipakai. Dokumen YAML yang lolos validasi di CI bisa gagal di produksi karena variabel lingkungan wajib tidak ada. Alat Pratinjau Substitusi Env YAML memungkinkan Anda mempratinjau dokumen YAML yang diperluas dengan sekumpulan nilai variabel tertentu sebelum deployment.

• $VAR tanpa nilai bawaan: gagal diam-diam jika VAR tidak diatur — substitusikan string kosong
• Sintaks ${VAR:-default}: mundur ke "default" jika VAR tidak diatur — uji kedua jalur
• Sintaks ${VAR:?error message}: melempar kesalahan eksplisit jika VAR tidak diatur — diutamakan untuk variabel wajib
• Substitusi tanpa tanda kutip yang diawali kurung kurawal: parser memperlakukan substitusi variabel sebagai mapping flow — selalu beri tanda kutip

Memperbaiki kesalahan YAML satu per satu cepat sekali Anda mengenali kategorinya. Mencegahnya mencapai produksi membutuhkan seperangkat kecil kebiasaan konsisten dan pemeriksaan otomatis.

Konfigurasi editor

Atur editor Anda memakai indentasi dua spasi untuk berkas YAML, menyisipkan spasi alih-alih tab, dan mengaktifkan whitespace yang terlihat. Di VS Code, pasang ekstensi YAML dari Red Hat yang menyediakan pemeriksaan sintaks real-time, validasi skema (untuk Kubernetes, GitHub Actions, dan format lain dengan JSON Schema yang dipublikasikan), serta autocompletion. Tambahkan berkas .editorconfig ke proyek Anda untuk menegakkan pengaturan ini bagi setiap anggota tim apa pun konfigurasi editor lokal mereka.

• Pengaturan .editorconfig untuk YAML: indent_style = space, indent_size = 2, trim_trailing_whitespace = true
• VS Code: pasang ekstensi YAML (Red Hat) — ia memvalidasi skema dan sintaks secara real-time
• IDE JetBrains: aktifkan dukungan YAML dan atur level inspeksi ke Warning untuk kesalahan struktural
• Vim/Neovim: gunakan yaml-language-server via nvim-lspconfig untuk diagnostik inline
• Prettier: memformat YAML secara konsisten — mencegah drift whitespace dan indentasi antar anggota tim

Validasi otomatis dalam CI/CD

Tambahkan langkah linting YAML ke pipeline CI Anda yang berjalan pada setiap pull request yang menyentuh berkas .yaml atau .yml apa pun. yamllint adalah alat CLI standar — ia memvalidasi sintaks, memeriksa kunci duplikat, menegakkan batas panjang baris, dan menangkap masalah konversi string truthy. Konfigurasikan dengan berkas .yamllint.yaml di akar proyek dan tambahkan sebagai hook pre-commit atau langkah CI yang berjalan sebelum job deployment apa pun.

Disiplin review kode

Diff YAML dalam review kode menjebak mudah disetujui tanpa menangkap kesalahan. Indentasi dua spasi versus empat spasi tampak seperti preferensi format tetapi mengubah struktur dokumen. Kunci yang dipindah ke tingkat indentasi lain mengubah blok induknya. Gunakan Penyorot Diff untuk Config JSON/YAML untuk meninjau perubahan YAML secara semantik — ia menunjukkan kunci mana yang ditambahkan, dihapus, atau diubah berdasarkan nilai, bukan berdasarkan diff baris mentah, membuat perubahan struktural langsung terlihat.