Troubleshooting

Build e Node

Sintomo	Causa	Rimedio
Node.js v22.x is not supported by Astro	Node troppo vecchio	usa Node 24 (o ≥22.23.4)
[postcss] ENOENT ... tailwindcss	astro.config.mjs è una funzione: vite.plugins perso	torna a un oggetto statico
Unexpected JSX expression su .tsx	manca jsx: "react-jsx"	aggiungilo in tsconfig.json
Tutte le collezioni vuote	WordPress spento o URL sbagliata	controlla WORDPRESS_API_BASE_URL, avvia WP
The collection "x" does not exist or is empty	collezione vuota (loader fallito)	connetti WP; se è un errore di contratto, leggi il warning sopra
Dopo un crash restano warning strani	cache .astro incoerente	rm -rf .astro dist e ricostruisci
Build rossa solo in CI	ENABLE_HTML_FALLBACK=false e contratto rotto	allinea mu-plugin e schema, non disattivare il flag

Contratto dati

Sintomo	Causa	Rimedio
meta: {}	CPT senza custom-fields o permalink non rigenerati	aggiungi custom-fields in supports, salva i permalink
expected string, received undefined	meta non registrato o non allineato	confronta CPT[...]['fields'] con lo schema Zod
Campo presente in admin ma non in REST	manca register_post_meta	registralo nello stesso file del CPT
JSON non salvato	sintassi JSON non valida	correggi il JSON; WordPress mostra un avviso
Booleani sempre false	tipo REST sbagliato	usa 'type' => 'boolean' con schema boolean
Numeri come stringhe	meta registrato come string	usa 'type' => 'integer'

Immagini

Sintomo	Causa	Rimedio
Immagine vuota	campo compilato con URL invece che ID	inserisci l’ID del media (numero)
Immagine 404	media eliminato	ricarica e riassegna
Immagine non ottimizzata	si usa <img> diretto	è voluto; valuta <Image> e image.domains

Form contatti

Sintomo	Causa	Rimedio
429	rate limit 60s per IP	attendi o testa da un’altra rete
400 con errors	validazione server	mostra gli errori; sono già mappati
Network error in locale	CORS o URL pubblica sbagliata	imposta PUBLIC_WORDPRESS_API_BASE_URL
201 ma nessuna mail	wp_mail/SMTP non configurato	configura SMTP sull’hosting, controlla spam
Honeypot compilato	bot (o autofill)	comportamento atteso

Webhook e deploy

Sintomo	Causa	Rimedio
Nessuna Action dopo un salvataggio	costanti HEADLESS_WEBHOOK_* mancanti	aggiungile in wp-config.php
Una sola Action per molte modifiche	debounce 60s	comportamento voluto
Action fallita	token GitHub scaduto o scope errato	PAT fine-grained con Contents: Read and write
Deploy verde ma niente online	secret WORDPRESS_API_BASE_URL assente	step saltati: aggiungi i secrets
Deploy fallito su FTP	credenziali/percorso	verifica FTP_* e FTP_REMOTE_DIR
Il sito mostra la versione vecchia	deploy non completato/cache	guarda il run, hard refresh

Deploy della guida (SSH/rsync)

Sintomo	Causa	Rimedio
La guida non si aggiorna	workflow non eseguito	controlla il trigger paths e i secrets GUIDE_SSH_*
Job verde ma niente online	GUIDE_SSH_HOST assente	aggiungi i quattro secrets
Redirect a api.jevis.it	manca il server block nginx	abilita deploy/nginx/headless.jevis.it.conf
Errore certificato	cert non emesso per il dominio	certbot --nginx -d headless.jevis.it
404 su tutte le pagine	document root sbagliata	GUIDE_REMOTE_DIR = root del server block
CSS non caricato	site diverso dal dominio reale	allinea site in guide/astro.config.mjs
Permission denied in rsync	utente SSH senza permessi sulla cartella	chown della document root all’utente di deploy
rsync: command not found	rsync assente sul VPS	sudo apt install rsync

Come indagare senza perdere tempo

1. Leggi la prima riga dell’errore: quasi sempre indica il file e il campo.
2. Se è un errore di build, riproduci in locale con ENABLE_HTML_FALLBACK=false.
3. Isola: la collezione che fallisce è indicata nel nome del loader.
4. Confronta il JSON reale con lo schema: curl dell’endpoint + occhio sui nomi.
5. Se hai cambiato la config, cancella .astro prima di ricostruire.
6. Non “aggiustare” disattivando il fallback in CI: nasconde il problema.