# Problemas comuns

> Os erros que as pessoas mais encontram, o que cada um significa e qual página os resolve.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/troubleshooting/common-problems/

## O que você vai aprender

- como ler um erro: o seu código, a sua dica e se ele pode ser repetido;
- os erros mais comuns, com a causa e a correção;
- como reunir o que um relatório de bug precisa.

## A ideia

Toda falha tem um código estável que começa com `E_`, uma mensagem, uma dica e um indicador `retryable`. A CLI os imprime, e os devolve como campos com `--json`; a API HTTP os devolve como campos, e o servidor MCP em um resultado de erro. Um erro **repetível** pode ser repetido com segurança depois de uma curta espera; a CLI sai com `2` para ele e com `1` para uma falha que repetir não resolve. A lista completa está na [referência de códigos de erro](/docs/reference/error-codes).

## Início rápido

1. Encontre o código na tabela abaixo.
2. Siga a sua correção, ou a página que ele indica.
3. Se o problema continuar, execute `vukem-video doctor --full` e leia as verificações que falham, depois [gere um pacote de diagnóstico](/docs/troubleshooting/diagnostic-bundle).

| Código | O que significa | Correção |
| --- | --- | --- |
| `E_WORKSPACE_LOCKED` | outro processo é dono do espaço de trabalho e não pode ser alcançado | [O espaço de trabalho está bloqueado](/docs/troubleshooting/workspace-locked) |
| `E_FFMPEG_MISSING` | nenhum FFmpeg utilizável, ou falta um codificador, filtro ou muxer necessário | [O FFmpeg não é encontrado](/docs/troubleshooting/ffmpeg-missing) |
| `E_NO_ENCODER` | nenhum codificador H.264 passou na codificação de teste | [Nenhum codificador H.264 funciona](/docs/troubleshooting/no-encoder) |
| `E_UNAUTHORIZED` | o token, a chave ou a sessão está ausente ou é inválido | no modo local, o token está em `<workspace>/token` (`vukem-video token:rotate` cria um novo); no modo de rede, entre ou use uma [chave de API](/docs/self-hosting/api-keys) |
| `E_FORBIDDEN` | a chave não tem o escopo, ou é limitada a outro projeto | crie uma chave com o escopo de que a chamada precisa |
| `E_REVISION_CONFLICT` | o projeto mudou desde o seu `base_revision` | leia o projeto de novo, refaça o lote e reenvie; veja [Lotes e revisões](/docs/agents/batches) |
| `E_ASSET_NOT_READY` | a mídia ainda está em ingestão | espere por `ready`, depois repita |
| `E_PATH_NOT_ALLOWED`, `E_FILE_NOT_FOUND`, `E_UNSUPPORTED_MEDIA`, `E_LIMIT_EXCEEDED` | uma importação foi recusada | [Uma importação falha](/docs/troubleshooting/import-fails) |
| `E_LINT_BLOCKING` | uma exportação foi recusada porque o `lint` encontrou erros | execute `vukem-video lint`, corrija os achados em `details.findings`, exporte de novo |
| `E_QUEUE_FULL`, `E_RATE_LIMITED` | um limite de concorrência ou de taxa foi atingido | espere (a resposta traz `Retry-After` para o limite de taxa) e repita; veja [Tarefas](/docs/guide/jobs) |
| `E_EXPORT_FAILED`, `E_VERIFY_FAILED` | o processo de exportação falhou, ou o seu arquivo não passou na verificação | leia `details.reason` ou `details.checks`, depois [A exportação está lenta](/docs/troubleshooting/slow-export) e o pacote de diagnóstico |

## Erros comuns

- Repetir um erro que não pode ser repetido. Um `E_VALIDATION` ou `E_LINT_BLOCKING` dá a mesma resposta até você mudar a requisição.
- Ler apenas a mensagem. A dica e o `details` dizem o que mudar.
- Excluir arquivos no espaço de trabalho para resolver um problema. Nada ali é seguro de remover à mão; use `vukem-video doctor --gc` para o que nenhum projeto referencia.
- Relatar um bug sem a versão. Execute `vukem-video version` e anexe o pacote de diagnóstico, que é limpo de valores secretos e guarda o documento de um projeto apenas quando você pede.

## Próximos passos

- [O pacote de diagnóstico](/docs/troubleshooting/diagnostic-bundle)
- [Códigos de erro](/docs/reference/error-codes)
