Guida

Errori YAML comuni

Sei errori causano quasi ogni parsing fallito. Ecco cosa significa ciascuno — e la correzione esatta.

Di yamltojsonfree · Pubblicato il 25 agosto 2026 · Aggiornato il 1 settembre 2026

Perché gli errori YAML sono così difficili da leggere

YAML costruisce la struttura dall’indentazione, quindi quando qualcosa va storto il parser spesso non riesce a dire cosa è andato storto — solo che la struttura ha smesso di avere senso. Per questo una parentesi non chiusa alla riga 12 viene regolarmente segnalata come «indentazione errata» alla riga 50: il parser ha continuato a consumare righe, cercando un delimitatore di chiusura mai arrivato, e si è arreso solo molto più tardi.

Gli errori qui sotto sono elencati per causa reale, non per il messaggio che stampa un parser. Se preferisci farli diagnosticare automaticamente, incolla il documento nel validatore YAML o nel convertitore da YAML a JSON — ciascuno di questi errori viene rilevato per quello che è, con la riga, una spiegazione chiara e una correzione suggerita.

I sei errori, nel dettaglio

I sei errori di sintassi YAML più comuni sono: (1) un tab usato per l’indentazione, (2) un valore senza virgolette contenente due punti, (3) una parentesi, una graffa o una virgoletta non chiusa, (4) una chiave duplicata, (5) un alias a un anchor inesistente e (6) chiavi sorelle indentate diversamente.

1. Un carattere di tabulazione viene usato per l’indentazione

Perché: YAML vieta del tutto i tab per l’indentazione, perché la loro larghezza è ambigua tra un editor e l’altro.

Soluzione: Sostituisci ogni tab con spazi — due per livello è la convenzione. La maggior parte degli editor lo fa con «converti indentazione in spazi».

2. Un valore senza virgolette contiene due punti

Perché: title: foo: bar è ambiguo — il parser non può capire quale dei due punti separa la chiave dal valore.

Soluzione: Metti il valore tra virgolette: title: 'foo: bar'.

3. Una parentesi, una graffa o una virgoletta non viene mai chiusa

Perché: Le collezioni flow come [80, 443] e le stringhe tra virgolette devono chiudersi sulla stessa riga logica. La maggior parte dei parser lo segnala come errore di indentazione molte righe dopo.

Soluzione: Aggiungi il delimitatore di chiusura, oppure riscrivi il valore in stile blocco con una voce per riga.

4. La stessa chiave compare due volte

Perché: I mapping YAML richiedono chiavi univoche, e così gli oggetti JSON. Tenere in silenzio l’ultimo valore nasconderebbe un bug reale.

Soluzione: Rinomina o rimuovi il duplicato — oppure indentalo di un livello se doveva essere una sotto-chiave.

5. Un alias punta a un anchor che non esiste

Perché: *nome fa riferimento a un anchor definito con &nome. Gli anchor devono comparire nel documento prima degli alias che li usano.

Soluzione: Definisci prima l’anchor e controlla l’ortografia — i nomi degli anchor distinguono maiuscole e minuscole.

6. Le chiavi sorelle sono indentate diversamente

Perché: Ogni chiave dello stesso blocco deve stare alla stessa indentazione. Due spazi su una riga e tre sulla successiva chiudono il blocco in anticipo.

Soluzione: Rendi identica l’indentazione di tutte le chiavi sorelle.

Due correzioni, prima e dopo

I due errori in cui ci si imbatte più spesso, mostrati come YAML errato accanto alla forma corretta.

Due punti senza virgolette in un valore

I secondi due punti rendono la riga ambigua; mettere tra virgolette l’intero valore risolve.

Errato

title: Deploy: production
owner: platform team

Corretto

title: "Deploy: production"
owner: platform team

Indentazione irregolare tra sorelle

«ports» sta a tre spazi mentre le sue sorelle stanno a due, quindi il blocco termina in anticipo.

Errato

server:
  host: localhost
   ports:
    - 8080

Corretto

server:
  host: localhost
  ports:
    - 8080

Quando lo YAML è valido ma comunque sbagliato

Un documento può essere analizzato perfettamente e significare comunque qualcosa che non intendevi. Il caso classico è country: NO, YAML valido in ogni versione — ma letto come la stringa "NO" in YAML 1.2 e come il booleano false in YAML 1.1. Tutta questa classe di cambi di tipo silenziosi è trattata nella guida YAML 1.1 contro 1.2.

Riferimenti

Specifica YAML 1.2.2 — le regole di indentazione, collezioni flow, anchor e chiavi univoche
YAML 1.2.2 §6.1 Spazi di indentazione — perché i tab non sono consentiti
Documentazione PyYAML — i messaggi di errore che vede la maggior parte degli utenti Python
js-yaml — il parser dietro gli strumenti di questo sito

Correggi il tuo YAML adesso

Ogni errore di questa pagina viene rilevato con la riga esatta e una correzione suggerita dagli strumenti gratuiti di questo sito. Niente viene caricato — tutto gira nel tuo browser.

YAML 1.1 vs 1.2

Perché country: NO può diventare false e come scrivere YAML sicuro.

Leggi la guida

Convertire YAML in JSON nel codice

Esempi Python, Node.js, Go e yq per conversioni ripetibili.