> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migraflow.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Problemas comuns da CLI

> Diagnóstico de instalação, autenticação, entrada e respostas da API.

## `migraflow` não é reconhecido

Ative o ambiente virtual no qual o pacote foi instalado e execute `python -m pip show migraflow-cli`. Reinstale com `python -m pip install .` se o pacote não aparecer.

## API key não encontrada

Confirme a variável no mesmo terminal que executará o comando. Nunca cole o valor em tickets ou logs.

```powershell theme={null}
$env:MIGRAFLOW_API_KEY
```

```bash theme={null}
test -n "$MIGRAFLOW_API_KEY" && echo configurada
```

## Arquivo não encontrado

Use caminho absoluto ou confirme o diretório atual. O arquivo deve estar codificado preferencialmente em UTF-8.

## Schema inválido

Execute primeiro `--validate`. Para dumps grandes, isole o DDL do escopo e remova comandos operacionais que não descrevem estruturas, sem alterar a evidência original.

## HTTP 401 ou 403

A credencial está ausente, inválida, expirada ou não possui perfil de consultor. Solicite rotação pelo canal autorizado.

## HTTP 429

Há limitação temporária de chamadas. Aguarde e evite execuções paralelas do mesmo assessment.

## HTTP 500 ou resposta incompleta

Preserve horário, versão da CLI, endpoint, dialeto e identificador de correlação quando exibido. Não anexe DDL ou chave a um ticket sem canal seguro. Tente `--validate` para separar falha de entrada de falha da análise completa.

## O SQL foi gerado, mas há findings críticos

Isso não é sucesso de migração. Revise `risk_report.md`, resolva os gaps, execute com `--review` e teste em ambiente descartável.