Como corrigir context deadline exceeded no Ollama
O erro context deadline exceeded no Ollama é um timeout Go durante pull ou requisição. Descubra se o limite vem do cliente, carga do modelo ou nginx.
O que significa realmente "context deadline exceeded"
O erro do Ollama context deadline exceeded indica um timeout. Algum código Go definiu um prazo para uma operação, a operação não terminou dentro desse prazo e o prazo expirou. Na maioria dos casos, essa operação é um pedido à espera de um modelo. Nada falhou e nenhum ficheiro está corrompido. O trabalho ainda estava a decorrer quando o tempo terminou.
A mensagem vem do pacote padrão context do Go, o que por si só fornece uma pista útil. Um cliente Python baseado em httpx gera httpx.ReadTimeout. Um browser mostra um erro de rede genérico. Se está a ler exatamente estas palavras, um programa Go deixou de esperar: a ferramenta de linha de comandos Ollama, o próprio servidor Ollama ou uma aplicação Go que chama a API (application programming interface).
O prazo nem sempre se refere à resposta de um modelo. As mesmas palavras também aparecem durante transferências: ollama pull ou a transferência que ollama run inicia quando o modelo ainda não está no disco. O issue #17484 do Ollama, reportado na versão 0.32.5, mostra ollama run de um modelo Hugging Face a imprimir as linhas pulling e depois Error: context deadline exceeded, enquanto o log do servidor mostra uma transferência de blob de hf.co a falhar com o mesmo erro. Se o seu output parar imediatamente depois das linhas pulling, o prazo aplica-se à transferência. Nesse caso, tente novamente o pull e verifique o caminho de rede até ao registry antes de alterar qualquer definição abaixo.
Quando o modelo já está no disco, estão envolvidas cinco camadas. Três definem o seu próprio prazo: o cliente, o timeout de carregamento do modelo no servidor e um reverse proxy. As outras duas, keep_alive e num_ctx, não definem nenhum prazo, mas determinam quanto trabalho tem de caber dentro de um deles. Cada camada falha num ponto diferente e requer uma correção diferente. O objetivo é identificar qual delas está por trás do erro.
- O seu cliente HTTP, que atribuiu ao pedido um orçamento de tempo fixo.
- O timeout de carregamento do modelo no servidor Ollama, que é acionado enquanto um modelo grande é lido do disco pela primeira vez.
keep_alive, que descarrega o modelo entre pedidos e faz com que a chamada seguinte volte a pagar o custo do carregamento.- Um
num_ctxsuficientemente grande para que o processamento do prompt demore minutos numa máquina apenas com CPU. - Um reverse proxy como nginx ou Traefik, que termina a ligação antes de o Ollama responder.
Percorra essa lista pela ordem indicada. Cada passo abaixo elimina uma camada da análise e evita que tenha de trabalhar por tentativa e erro.
Reproduza a chamada diretamente na API para retirar o proxy da equação
Execute o pedido no próprio servidor, diretamente para o Ollama, sem nenhum proxy pelo caminho.
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 não define um limite de tempo total, apenas um tempo limite de ligação. Por isso, este comando aguarda o tempo que o Ollama precisar. Isto divide o problema em duas partes. Se for devolvido um corpo JSON, o Ollama respondeu e o limite pertence a algum componente à sua frente. Se esta chamada ficar bloqueada durante vários minutos, o atraso está dentro do Ollama e o proxy não é a causa.
Agora envie o mesmo pedido através do URL público e meça o tempo.
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}'Um estado 504 apresentado depois de um número de segundos suspeitosamente redondo, como 60.0 ou 30.0, indica um tempo limite do proxy. Os proxies usam valores predefinidos redondos. Um modelo não termina exatamente aos 60.000 segundos duas vezes seguidas. Se a chamada direta for recusada imediatamente, em vez de demorar, o problema está no listener e não no tempo limite. qual endereço o Ollama usa para escutar na porta 11434 explica esse caso.
Monitore o log do servidor enquanto o pedido é processado
Abra uma segunda sessão e acompanhe o log do serviço. Em seguida, envie o pedido novamente.
journalctl -u ollama --no-pager --follow --pager-endUm arranque a frio normal regista o carregamento do modelo, depois o arranque de um runner e, por fim, o processamento do pedido. Um carregamento falhado aparece assim nas versões atuais, conforme verificado no código-fonte da 0.40.11 em outubro de 2026. Esta é a mensagem que identifica o tempo limite de carregamento interno do servidor:
timed out waiting for llama-server to start - <last error from the runner>As versões mais antigas, como a 0.12.0, apresentam a mensagem como timed out waiting for llama runner to start - progress 0.00 -. Em ambos os casos, o processo do modelo não terminou o arranque dentro do tempo disponível para o servidor. Na mensagem antiga, o valor de progresso indica até que ponto o processo avançou. 0.00 significa que o runner não comunicou qualquer informação antes do prazo, o que normalmente indica que o ficheiro ainda está a ser lido ou que a máquina está a usar swap. As versões atuais removem o valor de progresso e acrescentam o último erro do runner. Esse campo fica vazio quando não ocorreu nenhum erro. Se o log indicar que a ligação do cliente foi fechada antes de o llama-server terminar o carregamento, o chamador, o seu cliente ou um proxy à frente do servidor desistiu primeiro e o carregamento foi abortado. Para obter mais detalhes durante o carregamento, reinicie o serviço com OLLAMA_DEBUG=1 definido e repita o processo.
Meça se o atraso vem do carregamento ou da geração
Ollama informa os próprios tempos, por isso não precisa de adivinhar esta parte.
ollama run --verbose llama3.1:8b "Why is the sky blue?"Depois da resposta, ele apresenta total duration, load duration, prompt eval count, prompt eval rate, eval count e eval rate. Execute o comando duas vezes. Na segunda execução, load duration deve diminuir para quase zero, porque o modelo já está residente. Se não diminuir, o modelo está a ser descarregado entre as duas execuções. Esse é o caso keep_alive descrito mais abaixo.
Os mesmos valores são devolvidos pela API no objeto JSON final, como load_duration, prompt_eval_duration e eval_duration. A documentação indica que todas as durações são devolvidas em nanossegundos. Divida por 10^9 para obter os segundos.
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")})'Leia o maior valor. Se load_duration dominar, existe um problema no carregamento do modelo. Avance para as duas secções seguintes. Se prompt_eval_duration dominar, o processamento do prompt é o custo principal. Avance para a secção num_ctx. Se eval_duration dominar, o modelo está simplesmente a gerar a resposta lentamente neste hardware. Nenhuma configuração de timeout vai alterar isso. Reduza o tamanho da saída com num_predict ou utilize um modelo menor.
Aumente OLLAMA_LOAD_TIMEOUT depois de verificar a versão
A variável do servidor que controla este comportamento é OLLAMA_LOAD_TIMEOUT. No código-fonte da versão 0.40.11, verificado em outubro de 2026, ela é descrita como o período durante o qual o carregamento do modelo pode ficar bloqueado antes de ser interrompido. O valor predefinido é 5 minutos, e cada indicação de progresso no carregamento reinicia esse período. A variável nem sequer existe em versões mais antigas, como 0.3.0. Por isso, leia o valor predefinido da sua versão, em vez de o obter de qualquer artigo, incluindo este. Imprima primeiro a versão.
ollama --versionEm seguida, abra o código-fonte dessa tag exata, https://github.com/ollama/ollama/blob/<your version>/envconfig/config.go, e procure OLLAMA_LOAD_TIMEOUT. O valor nesse ficheiro é o valor predefinido compilado no seu binário. Defina o seu próprio valor através de um drop-in do systemd.
sudo systemctl edit ollama.serviceAdicione as variáveis numa secção [Service]. Este é o método indicado pela documentação do próprio Ollama para Linux:
[Service]
Environment="OLLAMA_LOAD_TIMEOUT=15m"
Environment="OLLAMA_KEEP_ALIVE=-1"sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property=EnvironmentO último comando imprime o ambiente que o serviço recebeu efetivamente. Um resultado vazio significa que o drop-in foi guardado fora dos marcadores do editor ou numa secção com um nome incorreto. Nesse caso, nenhuma das definições está em vigor. É importante compreender o que esta alteração faz: um tempo limite de carregamento maior impede o servidor de desistir, mas não torna o carregamento mais rápido. Se o modelo não couber na memória, a máquina usará swap, o carregamento ficará muito lento e um valor maior apenas adiará a falha.
Por que a primeira solicitação depois de uma pausa é lenta
Ollama descarrega um modelo inativo para libertar memória. A configuração keep_alive define quando isso acontece. A documentação do Ollama indica 5 minutos como valor predefinido, verificado em outubro de 2026. Assim, uma aplicação de chat usada uma vez por hora volta a carregar o modelo em cada mensagem, e cada mensagem suporta todo o arranque a frio. A solicitação que excede o tempo limite é a primeira depois de um período sem atividade. Esse é exatamente o padrão que muitas pessoas descrevem como aleatório.
Verifique o que está residente neste momento:
ollama ps
curl -s http://127.0.0.1:11434/api/psUma lista vazia, ou uma expiração prevista para os próximos minutos, confirma o problema. keep_alive aceita uma cadeia de duração, como "10m" ou "24h", um número simples de segundos, 0 para descarregar imediatamente, e um número negativo para manter o modelo na memória indefinidamente. Defina esse valor por solicitação ou defina OLLAMA_KEEP_ALIVE no serviço para todas as solicitações. O valor da solicitação prevalece: a documentação do Ollama indica que o parâmetro da API keep_alive substitui a configuração OLLAMA_KEEP_ALIVE. Portanto, um cliente que envia o seu próprio keep_alive continua a descarregar o modelo segundo o seu próprio agendamento.
curl -s http://127.0.0.1:11434/api/generate -d '{
"model": "llama3.1:8b",
"keep_alive": -1
}'Uma solicitação com um modelo e sem prompt carrega o modelo e termina. Essa é a forma documentada de aquecer um servidor depois de um reboot. Deve ser incluída numa unidade systemd pequena, para que ninguém tenha de esperar pelo primeiro arranque a frio depois de um reboot. O custo é direto: um modelo mantido na memória ocupa essa memória indefinidamente. Num servidor pequeno, pode manter um modelo residente, não quatro. Manter um modelo residente entre solicitações explica o cálculo da memória e a unidade de aquecimento.
Porque um num_ctx elevado excede o tempo limite antes do primeiro token
Antes de escrever qualquer coisa, o modelo tem de ler todo o prompt. Essa fase chama-se prefill e é o que prompt eval mede. num_ctx define o comprimento do contexto, o que faz duas coisas em simultâneo. Limita o número de tokens que o modelo pode considerar e dimensiona a KV cache (key value cache) que o servidor aloca antecipadamente. Ambas aumentam o trabalho.
Num servidor apenas com CPU, o prefill é lento e cresce linearmente com o número de tokens do prompt. Um documento longo colado numa conversa pode passar minutos em prefill enquanto o cliente não mostra nada, porque o streaming ainda não começou. O cliente atinge o seu prazo e comunica context deadline exceeded, enquanto o servidor esteve a trabalhar durante todo esse tempo. Comprove-o usando os números da secção anterior. Envie o prompt longo e leia prompt_eval_count e prompt_eval_duration, que o Ollama define como o tempo gasto a avaliar os tokens não colocados em cache do prompt. Vários minutos nesses campos, com um eval_duration pequeno, indicam prefill. Como apenas os tokens não colocados em cache são contabilizados, repetir o mesmo prompt num modelo que ainda esteja carregado pode produzir um valor muito inferior. Por isso, compare as primeiras execuções. Para ver o custo de uma cache maior, execute o prompt com "options": {"num_ctx": 2048} e depois com 32768, e leia também load_duration, porque o tempo gasto a carregar o modelo é indicado nesse campo e não em prompt_eval_duration.
O valor predefinido do servidor vem de OLLAMA_CONTEXT_LENGTH, e um num_ctx por pedido no objeto options substitui-o. Aumentar esse valor até ao máximo anunciado para o modelo apenas porque esse máximo existe é o erro mais comum. A alocação da KV cache pode expulsar o modelo da RAM e transformar uma configuração funcional numa configuração que usa swapping. Escolher num_ctx de acordo com a memória disponível contém os detalhes do dimensionamento.
Por que o nginx retorna 504 Gateway Time-out
O nginx documenta proxy_read_timeout com um valor predefinido de 60s, e o log de erros identifica claramente a falha:
upstream timed out (110: Connection timed out) while reading response header from upstreamO detalhe importante está na documentação do nginx: o timeout "é definido apenas entre duas operações de leitura consecutivas, não para a transmissão da resposta inteira". Uma resposta em streaming reinicia o contador a cada bloco, por isso os chats em streaming continuam a funcionar. Uma solicitação com "stream": false não envia nada até a resposta estar completa, portanto toda a geração precisa terminar dentro dessa janela. É por isso que o mesmo modelo funciona na janela de chat, mas expira quando é chamado por um 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 para o streaming. Com o buffering ativado, o nginx pode acumular a resposta e entregá-la no final. Assim, os tokens deixam de aparecer um a um, e um stream funcional começa a parecer travado.
O Traefik aplica o mesmo controle no ServersTransport usado pelo router.
http:
serversTransports:
ollama:
forwardingTimeouts:
dialTimeout: "30s"
responseHeaderTimeout: "0s"
idleConnTimeout: "60s"responseHeaderTimeout cobre a espera pelos cabeçalhos da resposta depois que a solicitação é enviada, e zero significa que não há timeout. O serviço precisa referenciar o transport pelo nome com serversTransport: ollama. Caso contrário, você editou um bloco que não é usado.
Uma quantização menor carrega mais depressa porque há menos dados para ler
Quantização é a precisão com que os pesos são armazenados. Uma precisão menor significa um ficheiro mais pequeno, e carregar um modelo consiste sobretudo em ler esse ficheiro do disco para a memória.
Os dados por trás deste gráfico
[
{
"label": "q4_K_M",
"download_size_gb": 4.9
},
{
"label": "q8_0",
"download_size_gb": 8.5
},
{
"label": "fp16",
"download_size_gb": 16
}
]Estes são os tamanhos publicados na página do modelo, não medições feitas num servidor de teste. A versão 8B predefinida ocupa 4.9 GB. A versão de precisão total do mesmo modelo ocupa 16 GB: são mais de três vezes os bytes para ler e mais de três vezes a memória necessária para o manter. Num servidor alugado com armazenamento partilhado, essa diferença pode determinar se o carregamento termina ou excede o tempo limite. Calcular qual é o modelo adequado à sua RAM é a verificação a fazer antes de transferir algo grande.
O que alterar num servidor alugado
Aplique estas alterações pela ordem indicada pelas medições, uma de cada vez, e execute novamente o comando de medição depois de cada alteração.
- Fixe o modelo com
OLLAMA_KEEP_ALIVE=-1e aqueça-o no arranque, para que os pedidos dos utilizadores não suportem o custo do carregamento. Em seguida, confirme que nenhum cliente envia o seu própriokeep_alive, porque um valor no pedido substitui a definição do servidor. - Reduza
num_ctxpara o valor de que os seus prompts realmente precisam. Isto encurta o prefill e liberta a memória ocupada pela cache KV. - Utilize uma quantização menor, para que o carregamento leia menos bytes e o modelo deixe espaço para a cache.
- Aumente
proxy_read_timeoutno nginx ouresponseHeaderTimeoutno Traefik e desative o buffering, para que os tokens transmitidos cheguem ao cliente. - Aumente o timeout no seu próprio cliente, porque um programa Go ou Python com um limite de 30 segundos falhará perante qualquer modelo que demore mais tempo a processar o pedido.
Há outra causa comum por detrás de todos estes problemas. O Ollama processa um número limitado de pedidos em simultâneo e coloca os restantes numa fila. Assim, um segundo cliente pode ficar na fila até o seu próprio prazo expirar, sem que exista um modelo lento. O log do servidor mostra que o pedido foi processado tarde, e não que falhou. O que acontece quando várias pessoas partilham um servidor Ollama explica as definições de paralelismo, e a instalação base num VPS explica a configuração do serviço pressuposta por estas substituições.
FAQ
O que significa "context deadline exceeded" no Ollama?
Significa que um prazo expirou antes de terminar o trabalho que controlava. Na maioria dos casos, esse trabalho é um pedido à espera de um modelo, mas o mesmo erro também aparece durante transferências de modelos, em ollama pull ou no pull iniciado por ollama run. A expressão vem do pacote context do Go, por isso foi impressa por um programa Go: a ferramenta de linha de comandos do Ollama, o servidor Ollama ou uma aplicação Go que chama a API. Trata-se de um timeout, portanto não há nada avariado ou corrompido. Se a saída parar logo depois de linhas pulling, trate o problema como uma falha de transferência. Caso contrário, o passo seguinte é descobrir que camada definiu o prazo, porque o cliente, o carregamento do modelo e o reverse proxy definem os seus próprios prazos, enquanto keep_alive e num_ctx determinam quanto trabalho tem de caber dentro deles.
Devo aumentar o timeout do cliente ou o timeout do Ollama?
Faça primeiro uma medição. Envie o pedido com curl no próprio servidor, diretamente para http://127.0.0.1:11434, porque curl não impõe um limite de tempo global. Se essa chamada devolver um corpo JSON, o Ollama está a responder e o prazo pertence ao seu cliente ou ao seu proxy; aumente-o nessa camada. Se essa chamada também ficar bloqueada, o atraso está dentro do Ollama, e os campos load_duration e prompt_eval_duration da resposta indicam se o modelo está a ser carregado ou se está a ler o seu prompt.
Por que motivo o primeiro pedido excede o tempo limite e o seguinte funciona?
O Ollama descarrega um modelo inativo para libertar memória, segundo um agendamento definido por keep_alive. O valor predefinido documentado é 5 minutos, verificado em outubro de 2026. O primeiro pedido depois de um período de inatividade volta a carregar o modelo a partir do disco e suporta todo o arranque a frio. Um pedido enviado logo a seguir encontra o modelo residente e responde rapidamente. Execute ollama ps para ver o que está carregado e quando expira. Defina OLLAMA_KEEP_ALIVE=-1 para manter o modelo na memória e aceite que a memória continuará ocupada. Um cliente que envie o seu próprio keep_alive substitui essa definição, por isso verifique também os seus clientes.
Por que motivo só falha quando passo pelo nginx?
A documentação do nginx descreve proxy_read_timeout com um valor predefinido de 60s. Esse timeout aplica-se entre duas leituras sucessivas, e não à resposta inteira. Uma resposta em streaming reinicia o timeout a cada bloco, enquanto um pedido enviado com "stream": false tem de terminar dentro de uma única janela. É por isso que a janela de chat funciona e um script falha. Procure upstream timed out (110: Connection timed out) while reading response header from upstream no log de erros do nginx. Depois aumente proxy_read_timeout e defina proxy_buffering off.
Aumentar OLLAMA_LOAD_TIMEOUT torna o carregamento mais rápido?
Não. Apenas altera durante quanto tempo o servidor permite que um carregamento fique bloqueado antes de desistir e registar timed out waiting for llama-server to start ou timed out waiting for llama runner to start em builds mais antigos. Se o modelo não couber na memória, a máquina usa swap, o carregamento fica muito lento e um timeout maior apenas adia a falha, sem a corrigir. Verifique o valor predefinido da sua build executando ollama --version e lendo envconfig/config.go nessa tag. Depois, trate um carregamento que demora minutos como um sinal para transferir uma quantização menor.