Ir para o conteúdo

Troubleshooting

Guia para resolver problemas comuns.

O que capturar

Toda exceção do agrobr herda de AgrobrError. Nas fontes e nos datasets, o status HTTP de erro não sai como exceção do httpx: sai como SourceUnavailableError.

Exceção Significa
SourceUnavailableError A fonte não entregou o dado: timeout, falha de conexão ou status HTTP de erro. Em erros de status HTTP, a mensagem traz a fonte e o status; o atributo url guarda a URL, e __cause__ guarda a exceção original do httpx. No dataset, todas as fontes falharam: attempted_sources lista as tentadas, na ordem, errors traz o motivo de cada uma, e __cause__ é o erro da última
ParseError O dado chegou, mas o layout da fonte mudou e o parser não o lê
InvalidParameterError Parâmetro recusado antes da rede; também é ValueError
AgrobrError A base: captura qualquer erro do agrobr 
from agrobr import datasets
from agrobr.exceptions import AgrobrError, ParseError, SourceUnavailableError

try:
    df = await datasets.producao_anual("soja", ano=2023)
except SourceUnavailableError as erro:
    print(erro.attempted_sources, erro.errors)
except ParseError:
    ...
except AgrobrError:
    ...

Erros de Conexão

SourceUnavailableError

Causa: Fonte de dados não acessível após todas as tentativas.

Soluções:

  1. Verifique sua conexão com a internet
  2. Tente modo offline: 
    df = await cepea.indicador('soja', offline=True)
  3. Aguarde e tente novamente (fonte pode estar temporariamente fora)
  4. Verifique se há um proxy configurado que pode estar bloqueando

SourceFallbackWarning

Causa: A fonte primária falhou, mas o dataset conseguiu devolver dados de uma fonte alternativa. A mensagem informa a fonte original, o nome e o motivo resumido de cada fonte que falhou na cascata, na ordem das tentativas, e o fallback usado. A execução continua normalmente.

Timeout (SourceUnavailableError com ReadTimeout ou ConnectTimeout)

Causa: a fonte não respondeu no prazo. Esgotadas as tentativas, sai SourceUnavailableError; na maioria das fontes, a mensagem traz o tipo do timeout e after N attempts.

Soluções:

  1. Aumente o timeout de leitura: 
    export AGROBR_HTTP_TIMEOUT_READ=60
    No Comex Stat, o download inteiro tem teto próprio de 300 s; em rede lenta, suba AGROBR_HTTP_TIMEOUT_DOWNLOAD_COMEXSTAT (variáveis de ambiente).
  2. Verifique sua conexão
  3. Tente em horário de menor tráfego

403 Forbidden (CEPEA)

Causa: Cloudflare bloqueando requisições diretas ao CEPEA.

Solução: O agrobr automaticamente usa Notícias Agrícolas como fallback (httpx puro, sem Playwright). Se ainda falhar:

  1. Tente forçar atualização: 
    df = await cepea.indicador('soja', force_refresh=True)
  2. Use modo offline com dados do cache: 
    df = await cepea.indicador('soja', offline=True)

Erros de Parsing

ParseError

Causa: Layout da fonte mudou e parser não consegue extrair dados.

Soluções:

  1. Atualize o agrobr: 
    pip install --upgrade agrobr
  2. Verifique issues no GitHub para problemas conhecidos
  3. Use dados do cache enquanto o problema é corrigido: 
    df = await cepea.indicador('soja', offline=True)

Dados Vazios ou Incompletos

Causa: Fonte retornou dados parciais.

Verificações:

  1. O produto está correto? 
    produtos = await cepea.produtos()
print(produtos)
  2. O período solicitado tem dados?
  3. Tente um período menor

Erros de Validação

InvalidParameterError

Causa: Um parâmetro fornecido pelo usuário é inválido. Essa exceção também é um ValueError, para preservar compatibilidade com código que já captura ValueError, e interrompe a cascata sem mascarar o problema como fonte indisponível.

ValidationError

Causa: agrobr.exceptions.ValidationError só sai de validate_batch(..., strict=True) chamado pelo seu código, quando há anomalia crítica. O cepea.indicador não o levanta, com ou sem validate_sanity.

Anomalias estatísticas

Causa: Valores fora do range histórico esperado.

Com validate_sanity=True, anomalias são marcadas na coluna anomalies do DataFrame (não bloqueiam o retorno), registradas no log e resumidas (quantas linhas e quais regras) num UserWarning e em meta.validation_warnings. Não há exceção.

Isso é normal quando: - Preços tiveram variação atípica (eventos de mercado) - Dados de nova safra com volumes diferentes

Verificar: - Compare com outras fontes - Verifique notícias do setor

Erros de Cache

DuckDB Lock / Segfault em Multi-Thread

Causa: O DuckDB DuckDBPyConnection não é thread-safe. Se o agrobr é usado em um processo multi-thread (ex: MCP server, FastAPI com threads), chamadas concorrentes ao cache podem causar segfault ou deadlock.

Solução: A partir da v0.10.1, o DuckDBStore usa threading.Lock interno em todos os métodos. Se estiver em versão anterior, atualize:

pip install --upgrade agrobr

Cache corrompido

Causa: o agrobr.duckdb ficou ilegível (queda de energia, disco cheio ou antivírus no meio da gravação).

Solução: o agrobr move o banco danificado para agrobr.duckdb.corrompido-<AAAAMMDDHHMM>, avisa com os 2 caminhos e cria um banco novo na consulta seguinte. Se o aviso for o de cache indisponível (o arquivo estava em uso e não pôde ser movido), feche os outros processos do agrobr e apague o arquivo (recriado no próximo uso):

rm ~/.agrobr/cache/agrobr.duckdb

Tudo o que o agrobr grava, e como limpar: O que o agrobr grava no disco.

Cache não Atualizando

Causa: Cache fresh está sendo retornado.

Solução: 

df = await cepea.indicador('soja', force_refresh=True)

Problemas com Polars

ImportError: polars é necessário para as_polars=True

Causa: Polars não instalado.

Solução: 

pip install agrobr[polars]

Conversão Falha

Causa: Tipos incompatíveis na conversão pandas → polars.

Solução: Use pandas (default) e converta manualmente se necessário.

Problemas com CLI

Comando não encontrado: agrobr

Causa: CLI não instalada no PATH.

Soluções:

  1. Verifique instalação: 
    pip show agrobr
  2. Reinstale: 
    pip install --force-reinstall agrobr
  3. Use via Python: 
    python -m agrobr.cli cepea indicador soja

Encoding no Windows

Causa: Terminal não suporta UTF-8.

Solução: 

# PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# Ou exporte para arquivo
agrobr cepea indicador soja --formato csv > soja.csv

Debug

Habilitar Logs Detalhados

Como biblioteca, o agrobr não escreve log na saída padrão. Os logs passam pelo logging da biblioteca padrão, em JSON: sem configuração, só avisos e erros saem, na saída de erro.

# Via CLI (os logs vão para a saída de erro)
agrobr --verbose cepea indicador soja

import logging

logging.basicConfig(level=logging.DEBUG)             # todos os logs, na saída de erro

Para só o agrobr, em INFO:

import logging

logging.basicConfig()                                # um handler na saída de erro
logging.getLogger("agrobr").setLevel(logging.INFO)

Sem um handler, como o do basicConfig, o Python só imprime de WARNING para cima: o setLevel sozinho não mostra os logs de INFO.

O agrobr não configura o structlog: a configuração do structlog da sua aplicação vale só para os logs dela, e os do agrobr seguem no logging.

Ver Configuração Atual

agrobr config show

Verificar Health das Fontes

agrobr health           # todas as fontes
agrobr health --deep    # CEPEA: fingerprint contra a baseline do pacote + parse

Inspecionar Cache

agrobr doctor

Reportando Bugs

Se o problema persistir:

  1. Verifique se já existe issue: https://github.com/bruno-portfolio/agrobr/issues
  2. Colete informações: 
    python --version
pip show agrobr
agrobr doctor
  3. Abra issue com:
    • Versão do Python e agrobr
    • Sistema operacional
    • Código que causa o erro
    • Mensagem de erro completa
    • Logs de debug (se possível)

FAQ

O agrobr funciona em Jupyter?

Sim! Use a versão async diretamente: 

df = await cepea.indicador('soja')

Ou a versão sync: 

from agrobr.sync import cepea
df = cepea.indicador('soja')

Posso usar com proxies?

O agrobr não tem opção de proxy própria. Os clientes HTTP (o httpx e, na ANTAQ, o requests) seguem as variáveis HTTPS_PROXY, HTTP_PROXY e NO_PROXY do ambiente: nenhum deles desliga essa leitura. O Chromium do Playwright, usado pela CONAB, é aberto sem a opção proxy: o agrobr não repassa proxy a ele. Com proxy que reassina o TLS, veja também os certificados.

Os dados são gratuitos?

Sim, todas as fontes são públicas e gratuitas. O agrobr apenas facilita o acesso.

Com que frequência os dados são atualizados?

Fonte Frequência
CEPEA Diária (~18h)
CONAB Mensal
IBGE PAM Anual
IBGE LSPA Mensal