5 errori di .env che lasciano l'agente cieco

Perché un token 'presente' può essere invisibile all'agente

Bash legge i file .env in modi diversi a seconda del contesto. L'errore più comune non è il token mancante: è il token presente ma non esportato.

Un file .env con questa riga:

ghp_xxxxxxxxxxxx

non assegna nulla a nessuna variabile. È solo una stringa sullo standard input che bash carica e ignora.

La riga corretta è:

GH_TOKEN=ghp_xxxxxxxxxxxx

Stessa stringa, risultati opposti.

Come si manifesta il problema

Il sistema non crasha. Non esce con un codice di errore. L'agente semplicemente non vede le risorse che il token dovrebbe sbloccare.

Nel mio caso: gl-health è rimasto cieco su 8 Routine cloud per giorni. Zero errori in output. Il processo usciva con exit 0 ogni volta. Solo che non faceva nulla di utile.

È la firma del guasto silenzioso: exit 0 non significa 'ha funzionato'. Significa 'non è crashato'.

I 5 errori che rendono un token inutile

1. Token senza chiave. Forma sbagliata: ghp_xxx. Forma corretta: GH_TOKEN=ghp_xxx. Senza il KEY= davanti, bash non assegna la variabile.
2. Source senza export. Se fai source .env senza che le variabili siano marcate export, non passano ai processi figli. Fix: aggiungi export davanti a ogni riga, oppure usa set -a; source .env; set +a.
3. Spazi intorno all'uguale. GH_TOKEN = ghp_xxx (con spazi) viene interpretato come un comando, non come un'assegnazione. Bash non assegna nulla e di solito non avvisa.
4. Token con newline o spazio finale. Un token copiato dal browser può portare uno spazio invisibile alla fine. Il token arriva al server ma non viene riconosciuto. Fix: echo -n "$GH_TOKEN" | wc -c, controlla che la lunghezza sia quella attesa.
5. File .env non letto. Lo script parte, non fa source .env, e le variabili non esistono nell'environment di quel processo. Fix: aggiungi source "$(dirname "$0")/.env" all'inizio dello script, con il path corretto rispetto alla posizione del file.

Come verificare senza aspettare il guasto

Prima di lanciare un agente che dipende da un token:

source .env
echo "${GH_TOKEN:?GH_TOKEN non definito}" | head -c 20

Se il token manca o è vuoto, il comando esce con un errore esplicito prima che l'agente parta. L'output mostra i primi 20 caratteri, abbastanza per confermare che il token è quello giusto, non abbastanza per loggarlo intero.

Il pattern che uso adesso

Ogni script che ha bisogno di token nel mio sistema ha una sezione di verifica all'inizio:

source "$(dirname "$0")/.env"

: "${GH_TOKEN:?GH_TOKEN non definito}"
: "${ANTHROPIC_API_KEY:?ANTHROPIC_API_KEY non definita}"

La sintassi : "${VAR:?messaggio}" esce con errore se la variabile è vuota o non definita. Non è un check custom: è bash standard.

Se una variabile manca, lo script si ferma con un messaggio chiaro prima di fare qualsiasi altra cosa. Meglio uno stop esplicito all'inizio che un exit 0 silenzioso alla fine.

Una riga da aggiungere al monitoring

Se hai un sistema di monitoring che controlla i job, aggiungi un check esplicito sullo stato dei token prima che i job partino:

for var in GH_TOKEN ANTHROPIC_API_KEY RESEND_API_KEY; do
  if [[ -z "${!var}" ]]; then
    echo "WARN: $var non definita"
  fi
done

Questo gira prima di qualsiasi job che dipende da queste chiavi. Se un token è vuoto, lo sai prima che l'agente si avvii.

La regola

KEY=value. Sempre, senza eccezioni. Non solo value.

Un token nel .env senza la chiave davanti non è un token configurato: è una stringa persa in un file di testo.