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.
Início rápido#
- Encontre o código na tabela abaixo.
- Siga a sua correção, ou a página que ele indica.
- Se o problema continuar, execute
vukem-video doctor --fulle leia as verificações que falham, depois gere um pacote de diagnóstico.
| 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 |
E_FFMPEG_MISSING | nenhum FFmpeg utilizável, ou falta um codificador, filtro ou muxer necessário | O FFmpeg não é encontrado |
E_NO_ENCODER | nenhum codificador H.264 passou na codificação de teste | Nenhum codificador H.264 funciona |
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 |
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 |
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 |
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 |
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 e o pacote de diagnóstico |
Erros comuns#
- Repetir um erro que não pode ser repetido. Um
E_VALIDATIONouE_LINT_BLOCKINGdá a mesma resposta até você mudar a requisição. - Ler apenas a mensagem. A dica e o
detailsdizem 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 --gcpara o que nenhum projeto referencia. - Relatar um bug sem a versão. Execute
vukem-video versione anexe o pacote de diagnóstico, que é limpo de valores secretos e guarda o documento de um projeto apenas quando você pede.