Ollama: come risolvere context deadline exceeded
L'errore context deadline exceeded in Ollama segnala un timeout Go durante pull o richieste. Scopri se lo impone client, caricamento del modello o nginx.
Che cosa significa realmente “context deadline exceeded”
L’errore context deadline exceeded di Ollama indica un timeout. Una parte del codice Go ha impostato una scadenza per un’operazione, l’operazione non è terminata entro quel limite e la scadenza è stata superata. Nella maggior parte dei casi, l’operazione è una richiesta in attesa della risposta di un modello. Non si è verificato alcun arresto anomalo e nessun file è danneggiato. L’elaborazione era ancora in corso quando il tempo è scaduto.
La dicitura proviene dal pacchetto standard context di Go e costituisce già un’indicazione utile. Un client Python basato su httpx genera invece httpx.ReadTimeout. Un browser mostra un semplice errore di rete. Se leggi esattamente queste parole, un programma Go ha smesso di attendere: lo strumento da riga di comando di Ollama, il server Ollama stesso oppure un’applicazione Go che chiama l’API (application programming interface).
La scadenza non riguarda sempre la risposta di un modello. Le stesse parole possono comparire durante i download: ollama pull oppure il pull avviato da ollama run quando il modello non è ancora presente sul disco. Il problema #17484 di Ollama, segnalato nella versione 0.32.5, mostra ollama run di un modello Hugging Face che stampa le proprie righe pulling e poi Error: context deadline exceeded; il log del server mostra un recupero di un blob da hf.co che fallisce con lo stesso errore. Se l’output si interrompe subito dopo le righe pulling, la scadenza riguarda il download. Riprova quindi il pull e controlla il percorso di rete verso il registry prima di modificare una delle impostazioni riportate di seguito.
Quando il modello è già presente sul disco, sono coinvolti cinque livelli. Tre impostano una propria scadenza: il client, il timeout di caricamento del modello del server e un reverse proxy. Gli altri due, keep_alive e num_ctx, non impostano alcuna scadenza, ma determinano la quantità di lavoro che deve rientrare in una singola scadenza. Gli errori si verificano in punti diversi e richiedono correzioni diverse. L’obiettivo è quindi stabilire quale livello è all’origine dell’errore.
- Il client HTTP, che ha assegnato alla richiesta un budget di tempo fisso.
- Il timeout di caricamento del modello del server Ollama, che scade mentre un modello di grandi dimensioni viene letto dal disco per la prima volta.
keep_alive, che scarica il modello dalla memoria tra una richiesta e l’altra, obbligando la chiamata successiva a sostenere nuovamente il costo del caricamento.- Un
num_ctxabbastanza grande da richiedere diversi minuti soltanto per l’elaborazione del prompt su un sistema che usa esclusivamente la CPU. - Un reverse proxy come nginx o Traefik, che interrompe la connessione prima che Ollama abbia inviato la risposta.
Esamina l’elenco dall’alto verso il basso, nell’ordine indicato. Ogni passaggio seguente elimina un livello dall’analisi, così non devi procedere per tentativi.
Riprodurre la richiesta direttamente all’API per escludere il proxy
Eseguire la richiesta direttamente sul server, verso Ollama, senza proxy intermedi.
time curl -s http://127.0.0.1:11434/api/generate -d '{
"model": "llama3.1:8b",
"prompt": "Why is the sky blue?",
"stream": false
}' | head -c 400curl non imposta un limite di tempo complessivo, ma solo un timeout di connessione. Il comando quindi attende il tempo necessario a Ollama. In questo modo si divide il problema in due. Se viene restituito un corpo JSON, Ollama ha risposto e il timeout dipende da un componente a monte. Se invece questa chiamata resta in attesa per diversi minuti, il ritardo si verifica all’interno di Ollama e il proxy non è la causa.
Inviare ora la stessa richiesta tramite l’URL pubblico e misurarne la durata.
curl -s -o /dev/null -w '%{http_code} %{time_total}\n' \
-X POST https://llm.example.com/api/generate \
-d '{"model": "llama3.1:8b", "prompt": "hi", "stream": false}'Uno stato 504 visualizzato dopo un numero di secondi sospettosamente preciso, come 60.0 o 30.0, indica un timeout del proxy. I proxy usano valori predefiniti arrotondati. Un modello non termina due volte consecutive esattamente dopo 60.000 secondi. Se la chiamata diretta viene rifiutata immediatamente invece di rallentare, il problema riguarda il listener e non il timeout. In questo caso, vedere quale indirizzo usa Ollama per mettersi in ascolto sulla porta 11434.
Monitorare il log del server durante l'esecuzione della richiesta
Aprire una seconda sessione e seguire il log del servizio, quindi inviare nuovamente la richiesta.
journalctl -u ollama --no-pager --follow --pager-endUn avvio a freddo corretto registra il caricamento del modello, quindi l'avvio di un runner e infine la gestione della richiesta. Un caricamento non riuscito appare invece come segue nelle versioni attuali, verificato sul codice sorgente della 0.40.11 nell'ottobre 2026. Questa è la stringa che identifica il timeout interno del server per il caricamento:
timed out waiting for llama-server to start - <last error from the runner>Le build meno recenti, come la 0.12.0, lo formulano come timed out waiting for llama runner to start - progress 0.00 -. In entrambi i casi, il processo del modello non ha terminato l'avvio entro il tempo disponibile al server. Nella formulazione meno recente, il valore di avanzamento indica fin dove è arrivato il caricamento. 0.00 significa che il runner non ha riportato alcun dato prima della scadenza. Di solito significa che il file è ancora in lettura oppure che la macchina sta usando lo swap. Le build attuali non mostrano il valore e aggiungono l'ultimo errore del runner, che resta vuoto se non si è verificato alcun errore. Se invece il log avvisa che la connessione del client è stata chiusa prima che llama-server terminasse il caricamento, il chiamante, cioè il client o un proxy davanti al server, ha interrotto l'attesa per primo e il caricamento è stato annullato. Per ottenere maggiori dettagli durante il caricamento, riavviare il servizio con OLLAMA_DEBUG=1 impostato e ripetere l'operazione.
Misurare se il ritardo dipende dal caricamento o dalla generazione
Ollama restituisce i propri tempi, quindi non è necessario procedere per ipotesi.
ollama run --verbose llama3.1:8b "Why is the sky blue?"Dopo la risposta stampa total duration, load duration, prompt eval count, prompt eval rate, eval count e eval rate. Eseguire il comando due volte. Alla seconda esecuzione, load duration dovrebbe ridursi quasi a zero, perché il modello è già residente. Se non diminuisce, il modello viene scaricato tra le due esecuzioni. Questo è il caso keep_alive descritto più avanti.
Gli stessi valori vengono restituiti dall'API nell'oggetto JSON finale, come load_duration, prompt_eval_duration e eval_duration. La documentazione specifica che tutte le durate sono espresse in nanosecondi. Dividere quindi per 10^9 per ottenere i secondi.
curl -s http://127.0.0.1:11434/api/generate -d '{
"model": "llama3.1:8b",
"prompt": "Why is the sky blue?",
"stream": false
}' | python3 -c 'import json,sys; d=json.load(sys.stdin); print({k: round(v/1e9, 2) for k, v in d.items() if k.endswith("_duration")})'Considerare il valore più alto. Se prevale load_duration, il problema riguarda il caricamento del modello. Passare quindi alle due sezioni successive. Se prevale prompt_eval_duration, il costo è dovuto all'elaborazione del prompt. Passare alla sezione num_ctx. Se prevale eval_duration, il modello sta semplicemente generando lentamente su questo hardware e nessuna impostazione di timeout può cambiare il risultato. Ridurre la lunghezza dell'output con num_predict oppure usare un modello più piccolo.
Aumentare OLLAMA_LOAD_TIMEOUT dopo aver verificato la versione
La variabile del server che controlla questo comportamento è OLLAMA_LOAD_TIMEOUT. Nel codice sorgente della versione 0.40.11, verificato a ottobre 2026, viene descritta come l'intervallo per cui consentire il blocco del caricamento del modello prima di interromperlo. Il valore predefinito è 5 minuti e ogni segnale di avanzamento del caricamento riavvia il conteggio. La variabile non esiste nelle build precedenti, come 0.3.0. Leggere quindi il valore predefinito della build in uso invece di affidarsi a un articolo, incluso questo. Stampare prima la versione.
ollama --versionAprire quindi il codice sorgente del tag esatto, https://github.com/ollama/ollama/blob/<your version>/envconfig/config.go, e cercare OLLAMA_LOAD_TIMEOUT. Il valore presente in quel file è il valore predefinito compilato nel binario. Impostare un valore personalizzato tramite un drop-in di systemd.
sudo systemctl edit ollama.serviceAggiungere le variabili in una sezione [Service]. Questo è il metodo indicato dalla documentazione di Ollama per Linux:
[Service]
Environment="OLLAMA_LOAD_TIMEOUT=15m"
Environment="OLLAMA_KEEP_ALIVE=-1"sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property=EnvironmentL'ultimo comando stampa l'ambiente effettivamente ricevuto dal servizio. Un risultato vuoto indica che il drop-in è stato salvato fuori dai delimitatori dell'editor oppure nella sezione sbagliata. In tal caso, nessuna delle impostazioni definite è attiva. È importante chiarire il risultato ottenuto: un timeout di caricamento più lungo impedisce al server di interrompere il tentativo, ma non accelera il caricamento. Se il modello non entra in memoria, la macchina userà la swap, il caricamento procederà molto lentamente e un valore più alto sposterà soltanto il momento del fallimento.
Perché la prima richiesta dopo una pausa è lenta
Ollama scarica dalla memoria un modello inattivo per liberare memoria. L'impostazione keep_alive determina quando lo fa. La documentazione di Ollama indica come valore predefinito 5 minuti, secondo la verifica effettuata a ottobre 2026. Di conseguenza, un'applicazione di chat utilizzata una volta all'ora ricarica il modello a ogni messaggio, e ogni messaggio sostiene il costo completo dell'avvio a freddo. La richiesta che va in timeout è la prima dopo un periodo di inattività. È esattamente il comportamento che viene descritto come casuale.
Controlla quali modelli sono attualmente residenti in memoria:
ollama ps
curl -s http://127.0.0.1:11434/api/psUn elenco vuoto, oppure una scadenza prevista entro pochi minuti, lo conferma. keep_alive accetta una stringa di durata come "10m" o "24h", un semplice numero di secondi, 0 per scaricare subito il modello e un numero negativo per mantenerlo indefinitamente in memoria. Impostalo per ogni richiesta oppure configura OLLAMA_KEEP_ALIVE sul servizio per applicarlo a tutte le richieste. Il valore della richiesta ha la precedenza: la documentazione di Ollama indica che il parametro API keep_alive sovrascrive l'impostazione OLLAMA_KEEP_ALIVE. Pertanto, un client che invia un proprio keep_alive scarica comunque il modello secondo la propria pianificazione.
curl -s http://127.0.0.1:11434/api/generate -d '{
"model": "llama3.1:8b",
"keep_alive": -1
}'Una richiesta con un modello e senza prompt carica il modello e restituisce il risultato. Questo è il metodo documentato per preriscaldare un server dopo un riavvio. Va inserito in una piccola unità systemd, così nessuno deve attendere il primo avvio a freddo dopo un riavvio. Il costo è concreto: un modello mantenuto in memoria conserva la memoria allocata indefinitamente. Su un server di piccole dimensioni puoi quindi mantenerne uno in memoria, non quattro. Mantenere un modello residente tra le richieste illustra i calcoli della memoria e l'unità di preriscaldamento.
Perché un valore elevato di num_ctx causa un timeout prima del primo token
Prima di generare qualsiasi contenuto, il modello deve leggere l'intero prompt. Questa fase si chiama prefill ed è quella misurata da prompt eval. num_ctx imposta la lunghezza del contesto e svolge due funzioni. Limita il numero di token che il modello può prendere in considerazione e determina le dimensioni della KV cache (key value cache) che il server alloca in anticipo. Entrambi i fattori aumentano il carico di lavoro.
Su un server che usa solo la CPU, il prefill è lento e il tempo cresce linearmente con il numero di token del prompt. Un documento lungo incollato in una chat può richiedere diversi minuti di prefill, mentre il client non visualizza nulla perché lo streaming non è ancora iniziato. Il client raggiunge la scadenza e restituisce l'errore context deadline exceeded, mentre il server continua a elaborare la richiesta. Verificalo con i valori della sezione precedente. Invia il prompt lungo e leggi prompt_eval_count e prompt_eval_duration, che Ollama definisce come il tempo impiegato per valutare i token del prompt non presenti nella cache. Un valore di diversi minuti per questi campi, insieme a un valore ridotto di eval_duration, indica che il tempo è stato impiegato nel prefill. Poiché vengono conteggiati solo i token non presenti nella cache, una seconda esecuzione dello stesso prompt su un modello ancora caricato può restituire un valore molto più basso. Per questo, confronta le prime esecuzioni. Per verificare il costo di una cache più grande, esegui il prompt prima con "options": {"num_ctx": 2048} e poi con 32768. Leggi anche load_duration, perché il tempo impiegato per caricare il modello viene riportato in questo campo e non in prompt_eval_duration.
Il valore predefinito del server proviene da OLLAMA_CONTEXT_LENGTH. Un valore num_ctx specificato per la singola richiesta nell'oggetto options lo sostituisce. Aumentarlo fino al massimo dichiarato dal modello solo perché tale massimo è disponibile è l'errore più comune. L'allocazione della KV cache può infatti espellere il modello dalla RAM e trasformare una configurazione funzionante in una configurazione che usa lo swap. In Scegliere num_ctx in base alla memoria realmente disponibile trovi i dettagli per il dimensionamento.
Perché nginx restituisce 504 Gateway Time-out
nginx documenta proxy_read_timeout con un valore predefinito di 60s e il relativo log degli errori indica chiaramente il problema:
upstream timed out (110: Connection timed out) while reading response header from upstreamIl dettaglio importante è nella documentazione di nginx: il timeout «viene applicato solo tra due operazioni di lettura consecutive, non alla trasmissione dell’intera risposta». Una risposta in streaming reimposta il timer a ogni chunk, quindi le chat in streaming continuano a funzionare. Una richiesta con "stream": false non invia nulla finché la risposta non è completa, quindi l’intera generazione deve terminare entro quella finestra. Per questo lo stesso modello funziona nella finestra della chat, ma va in timeout quando viene chiamato da uno script.
location / {
proxy_pass http://127.0.0.1:11434;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
proxy_buffering off;
}sudo nginx -t && sudo systemctl reload nginxproxy_buffering off è importante per lo streaming. Con il buffering attivo, nginx può raccogliere la risposta e inoltrarla al termine. I token quindi non compaiono più uno alla volta e uno streaming funzionante può sembrare bloccato.
Traefik applica lo stesso controllo a ServersTransport utilizzato dal router.
http:
serversTransports:
ollama:
forwardingTimeouts:
dialTimeout: "30s"
responseHeaderTimeout: "0s"
idleConnTimeout: "60s"responseHeaderTimeout copre l’attesa degli header della risposta dopo l’invio della richiesta e il valore zero indica l’assenza di timeout. Il servizio deve fare riferimento al transport tramite il nome usando serversTransport: ollama, altrimenti hai modificato un blocco che non viene utilizzato.
Una quantizzazione più compatta si carica più velocemente perché richiede meno dati da leggere
La quantizzazione indica la precisione con cui vengono memorizzati i pesi. Una precisione inferiore produce un file più piccolo e il caricamento di un modello consiste soprattutto nella lettura di quel file dal disco e nel suo trasferimento in memoria.
I dati alla base di questo grafico
[
{
"label": "q4_K_M",
"download_size_gb": 4.9
},
{
"label": "q8_0",
"download_size_gb": 8.5
},
{
"label": "fp16",
"download_size_gb": 16
}
]Queste sono le dimensioni pubblicate nella pagina del modello, non misurazioni effettuate su un server di test. La build predefinita 8B occupa 4.9 GB. La build dello stesso modello a precisione completa occupa 16 GB: richiede la lettura di più del triplo dei byte e più del triplo della memoria per essere contenuta. Su un server a noleggio con storage condiviso, questa differenza determina se il caricamento termina correttamente o supera il timeout. Verificare quale modello è compatibile con la RAM è il controllo da eseguire prima di scaricare file di grandi dimensioni.
Modifiche da applicare a un server noleggiato
Applicale nell’ordine indicato dalle misurazioni, una alla volta, quindi esegui di nuovo il comando di misurazione dopo ciascuna modifica.
- Imposta il modello con
OLLAMA_KEEP_ALIVE=-1e precaricalo all’avvio, in modo che le richieste degli utenti non debbano sostenere il costo del caricamento. Verifica quindi che nessun client invii un propriokeep_alive, perché un valore nella richiesta sovrascrive l’impostazione del server. - Riduci
num_ctxa quanto richiedono effettivamente i prompt. In questo modo riduci il prefill e liberi la memoria occupata dalla cache KV. - Scarica una quantizzazione più piccola, così il caricamento legge meno byte e il modello lascia più spazio alla cache.
- Aumenta
proxy_read_timeoutin nginx oresponseHeaderTimeoutin Traefik e disabilita il buffering, in modo che i token trasmessi in streaming raggiungano il client. - Aumenta il timeout nel client che gestisci direttamente, perché un programma Go o Python con un limite di 30 secondi fallirà con qualsiasi modello che impiega più tempo per elaborare la richiesta.
C’è un’altra causa comune, indipendente da tutte queste impostazioni. Ollama gestisce contemporaneamente un numero limitato di richieste e accoda le altre. Di conseguenza, una seconda richiesta può restare in coda fino alla scadenza del proprio timeout, anche se non è presente alcun modello lento. Il log del server mostra che la richiesta viene servita in ritardo, non che è fallita. Cosa succede quando più persone condividono un server Ollama descrive le impostazioni del parallelismo, mentre l’installazione di base su un VPS descrive la configurazione del servizio presupposta da queste sovrascritture.
FAQ
Che cosa significa "context deadline exceeded" in Ollama?
Significa che una scadenza è trascorsa prima che terminasse l'operazione a cui si applicava. Nella maggior parte dei casi si tratta di una richiesta in attesa di un modello, ma lo stesso errore compare anche durante i download dei modelli, in ollama pull o nel pull avviato da ollama run. La frase proviene dal pacchetto context di Go, quindi è stata stampata da un programma Go: lo strumento da riga di comando di Ollama, il server Ollama o un'applicazione Go che chiama l'API. Si tratta di un timeout: non indica che qualcosa sia danneggiato o corrotto. Se l'output si è interrotto subito dopo le righe pulling, consideralo un problema di download. In caso contrario, il passaggio successivo consiste nell'individuare quale livello ha impostato la scadenza, perché il client, il caricamento del modello e il reverse proxy impostano ciascuno il proprio timeout, mentre keep_alive e num_ctx stabiliscono quanto lavoro deve rientrare nei rispettivi limiti.
Devo aumentare il timeout del client o quello di Ollama?
Prima esegui una misurazione. Invia la richiesta con curl direttamente sul server, a http://127.0.0.1:11434, perché curl non impone alcun limite di tempo complessivo. Se la chiamata restituisce un corpo JSON, Ollama sta rispondendo e la scadenza riguarda il client o il proxy: aumenta quindi il timeout in quel punto. Se anche la chiamata resta bloccata, il ritardo si trova all'interno di Ollama e i campi load_duration e prompt_eval_duration della risposta indicano se il modello è in fase di caricamento o se sta leggendo il prompt.
Perché la prima richiesta va in timeout e la successiva funziona?
Ollama scarica dalla memoria un modello inattivo per liberare risorse, secondo la pianificazione definita da keep_alive. Il valore predefinito documentato è di 5 minuti, verificato a ottobre 2026. La prima richiesta dopo un periodo di inattività ricarica il modello dal disco e sostiene interamente il costo dell'avvio a freddo, mentre una richiesta inviata subito dopo trova il modello già residente e restituisce rapidamente il risultato. Esegui ollama ps per vedere che cosa è caricato e quando scade. Imposta OLLAMA_KEEP_ALIVE=-1 per mantenere il modello in memoria, tenendo conto che la memoria resterà occupata. Un client che invia un proprio keep_alive sovrascrive questa impostazione, quindi controlla anche i client.
Perché il problema si verifica solo quando passo attraverso nginx?
nginx documenta proxy_read_timeout con un valore predefinito di 60s, e questo timeout si applica all'intervallo tra due letture consecutive, non all'intera risposta. Una risposta in streaming reimposta il timeout a ogni blocco, mentre una richiesta inviata con "stream": false deve completarsi all'interno di una singola finestra. Per questo la finestra della chat funziona mentre uno script non riesce. Cerca upstream timed out (110: Connection timed out) while reading response header from upstream nel log degli errori di nginx, quindi aumenta proxy_read_timeout e imposta proxy_buffering off.
Aumentare OLLAMA_LOAD_TIMEOUT rende più veloce il caricamento?
No. Modifica soltanto per quanto tempo il server consente a un caricamento di rimanere bloccato prima di interromperlo e registrare timed out waiting for llama-server to start, oppure timed out waiting for llama runner to start nelle build precedenti. Se il modello non entra in memoria, la macchina utilizza lo swap, il caricamento rallenta notevolmente e un timeout più lungo posticipa il fallimento senza risolvere il problema. Controlla il valore predefinito della tua build eseguendo ollama --version e leggendo envconfig/config.go in corrispondenza di quel tag, quindi considera un caricamento che richiede minuti come un segnale per scaricare una quantizzazione più piccola.