Solução de problemas

Os sintomas são agrupados pelo ponto em que aparecem no caminho da instalação até a exportação, com as falhas mais comuns dos novatos primeiro. Cada entrada nomeia a causa e o comando de solução.

🚧 Instalação e ambiente

uv sync falha

Causa: Python 3.12 ou mais recente não está no PATH, ou falta o uv. Solução: Confirme a versão do Python e execute novamente:

uv sync --all-extras --group dev

Se faltar o uv, instale-o a partir das instruções oficiais do pacote da Astral, abra um novo shell e execute o comando novamente.

O instalador relata um pré-requisito ausente

Causa: Os scripts de instalação exigem git e uv no PATH. Solução: Instale o pré-requisito nomeado e execute novamente o mesmo comando de instalação. Defina DISPATCHATLAS_HOME antes de executar novamente quando o checkout deve residir fora do diretório de dados de usuário padrão.

A atualização relata mudanças mas não as aplica

Causa: As verificações de atualização são somente leitura por padrão. Solução: Defina DISPATCHATLAS_REF com uma tag de versão ou um SHA de commit completo de 40 caracteres, depois aplique a atualização por checkout desanexado explicitamente:

$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Apply

export DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply

A desinstalação recusa um destino

Causa: Os scripts de desinstalação recusam caminhos vazios, raízes do sistema de arquivos, diretórios pessoais e diretórios sem a sentinela do espaço de trabalho do DispatchAtlas. Solução: Defina DISPATCHATLAS_HOME com o caminho do checkout instalado e execute novamente o comando de desinstalação.

📦 Importações

ModuleNotFoundError: No module named 'dispatchatlas'

Causa: O espaço de trabalho não está sincronizado, ou o script roda sob um interpretador Python fora do ambiente do projeto. Solução: A partir da raiz do repositório, sincronize e execute scripts através do uv para que o ambiente do projeto esteja ativo:

uv sync --all-extras --group dev
uv run python your-script.py

MissingOptionalDependencyError ao criar um solver

Causa: Backends pesados opcionais (solvers exatos, estimadores de aprendizado) permanecem atrás de extras e são sondados em tempo de execução, nunca importados durante a importação do pacote. O erro nomeia o extra ausente, sua finalidade e qualquer nota de licença. Solução: Instale o extra nomeado (por exemplo exact, exact-commercial ou learning) ou selecione um solver cujo backend esteja presente. As declarações de dependências dos solvers estão listadas em sistema de solvers.

🧪 Configuração e execução de campanhas

CampaignConfigError ao validar uma campanha

Causa: Um campo de configuração não passa na validação — um id vazio, uma semente ou orçamento não positivos, nomes de protocolo de parada duplicados, ou uma lista vazia de benchmarks, solvers ou objetivos. O erro carrega o caminho do campo que falha. Solução: Corrija o campo nomeado. A página do motor de campanhas documenta cada bloco de configuração, e experiments/configs/smoke-pilot.json é um exemplo de trabalho completo:

uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json

KeyError ao buscar um problema de benchmark

Causa: O id do problema não está no catálogo do provedor, ou uma string simples foi passada onde um ProblemId é esperado. Solução: Envolva o id (provider.get_problem(ProblemId("smoke-job-shop-0"))) e liste primeiro os ids disponíveis com provider.list_problem_ids() — veja os tutoriais.

A campanha completa se recusa a executar

Causa: Uma campanha no estágio full falha fechando com full-campaign execution requires statistical design approval até que essa aprovação seja registrada na configuração. Solução: Execute no estágio smoke ou pilot para verificações locais, ou registre a aprovação do projeto estatístico conforme prontidão da versão antes de habilitar a execução completa.

A retomada re-planeja em vez de pular execuções concluídas

Causa: O ponto de verificação em .checkpoints/{campaign_id}.json é protegido por um hash de configuração; qualquer mudança de configuração o invalida em vez de reutilizá-lo silenciosamente. Solução: Mantenha a configuração inalterada para retomar, ou aceite um plano novo sob a configuração alterada. O contrato do espaço de trabalho é descrito em campanhas reproduzíveis.

📤 Exportações, relatórios e o site

A exportação de análise relata um ponto de verificação ausente

Causa: O comando dispatchatlas export espera um diretório de campanha concluído com checkpoint.json, plan.json, environment.json e registros de resultados. Solução: Aponte --campaign-dir para o diretório de resultados da campanha em vez do seu pai, ou execute a campanha novamente:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core

Se --target-dir estiver fora do diretório de trabalho atual, passe um --authorized-output-root explícito que contenha o destino.

A validação de dados do portal falha

Causa: Os ativos do site estático estão dessincronizados em relação à exportação de resultados do portal. Solução: Regenere os ativos estáticos. O comando lê por padrão a exportação de resultados filtrada por divulgação e comprometida em exports/portal-results.json, então roda sem argumentos:

uv run python tools/build_site_assets.py

Passe --result-source para publicar uma exportação portal-results.json filtrada por divulgação diferente:

uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json

Se o comando relatar dispatchatlas site-assets: error, verifique se --result-source (ou o padrão exports/portal-results.json) aponta para um arquivo portal-results.json existente gerado pelo caminho de exportação de análise.

O portão de redação do portal falha

Causa: Um token que não pertence à superfície pública chegou aos dados do portal, então a compilação falha fechando para manter a face publicada lendo-se como um kit genérico de otimização de escalonamento. Solução: O erro lista cada artefato infrator, caminho de campo e token. Redija o campo infrator no construtor que emite esse artefato (sob tools/portal_contract.py ou sua evidência de origem) para que apenas evidência derivada segura para o público chegue aos dados do portal, depois regenere:

uv run python tools/build_site_assets.py

Essa falha é diferente de uma exportação de portal ausente: passar um --result-source diferente não a resolve — o token infrator deve ser removido em sua origem.

A compilação do site não encontra uma página

Solução: Execute os testes de contrato do site e a compilação da documentação:

uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check

Falta um solver nas recomendações

Causa: A seleção filtra por metadados. Solução: Verifique nos metadados do solver o suporte a objetivos, as tags de capacidade requeridas, o status de dependências opcionais e a visibilidade por nível de evidência em sistema de solvers.

Ainda travado? Veja as perguntas frequentes ou abra uma issue no repositório do GitHub.