Solução de problemas

Primeiro diagnóstico

Quando um comando falha:

1. Leia o código do erro e os próximos passos impressos pela CLI. Cada categoria de erro tem uma página em Erros da CLI.

2. Rode o diagnóstico do alvo:

   CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
   finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"

3. Se a falha foi num deploy, peça o diagnóstico da execução:

   CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
   finnest recover deploy --run=latest --cloud="$CLOUD" --environment="$ENVIRONMENT"

   O comando só lê as evidências. Ele indica em que etapa o deploy parou e qual o próximo comando seguro. Veja Recuperação de deploy.

4. Para acionar o suporte, gere o pacote de suporte e envie-o com o código do erro:

   finnest support bundle --run=<id-da-execução>

Evidências de execução

Cada comando grava uma evidência redigida em .finnest/runs/<comando>/<execução>/, no diretório onde foi executado:

Arquivo	Conteúdo
envelope.json	Resultado final: status, código de saída, alvo, resumo das etapas, erro e próximos passos.
events.ndjson	Eventos do comando, em ordem.
run.json e deploy-events.ndjson	No deploy: resumo da execução e eventos de cada etapa.
raw/pulumi-bootstrap.log	Saída da preparação do estado da infraestrutura.
raw/pulumi-deploy.log	Saída da criação da infraestrutura e do runtime.
raw/pulumi-destroy.log	Saída do destroy.

Para listar e abrir execuções anteriores:

finnest runs
finnest runs show <execução>

A CLI mantém as 25 execuções mais recentes e nunca apaga execuções que falharam.

Arquivos de configuração legados

Instalações antigas podiam apontar a CLI para arquivos de configuração do runtime, na seção [runtime] do finnest.toml (bootstrap_config, deploy_config) ou nas variáveis RUNTIME_CD_*_CONFIG_PATH. A CLI atual não precisa desses arquivos.

Configuração de bootstrap

Erros: BOOTSTRAP_CONFIG_FILE_MISSING, BOOTSTRAP_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.

O arquivo de bootstrap configurado não existe, não pode ser lido ou ainda tem valores __FINNEST_REQUIRED_… do modelo.

Configuração de deploy

Erros: DEPLOY_CONFIG_FILE_MISSING, DEPLOY_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.

O arquivo de deploy configurado não existe, não pode ser lido ou ainda tem valores do modelo.

Configuração de destroy

Erros: DESTROY_CONFIG_FILE_MISSING, DESTROY_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.

O arquivo usado pelo destroy não existe, não pode ser lido ou ainda tem valores do modelo.

Como corrigir

1. Remova a referência ao arquivo legado do finnest.toml (ou a variável RUNTIME_CD_*_CONFIG_PATH). Se o suporte Finnest pediu para manter o arquivo, restaure-o e preencha os valores pendentes.

2. Atualize os metadados da estação:

   finnest setup

3. Repita o comando que falhou.

Situações comuns

O deploy pede --yes

Todo --apply altera a nuvem e exige confirmação explícita:

CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes

O sandbox não responde

Nos modos de custo economy e standard, o cluster do sandbox é desligado fora do horário comercial. Para religar:

CLOUD=aws  # ou: azure
finnest resume --cloud="$CLOUD" --environment=sandbox

A sessão da nuvem expirou

Renove o login (AWS SSO ou az login) e rode finnest doctor de novo antes de repetir o deploy.

Falha nos testes de fumaça depois do deploy

Se o deploy parou na etapa smoke, a infraestrutura já está no ar. Corrija a causa apontada (normalmente certificado, credencial ou configuração regulatória) e rode só os testes:

CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
finnest smoke --cloud="$CLOUD" --environment="$ENVIRONMENT"