> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/opere/troubleshooting.md). # Troubleshooting Sintoma, causa provável, como confirmar, o que fazer. Comece pelo sintoma que você está vendo; cada linha aponta para a página com o detalhe. ## A aplicação não sobe ou não descobre as functions | Sintoma | Causa provável | Como confirmar | O que fazer | | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | "There is not Skail runtime available!" | Faltou `builder.UseSkail()` / `services.AddSkail()` | Ver `Program.cs` | Adicionar a chamada. Ver [Configuração do host](/referencia/sdk-csharp/configuracao-do-host.md) | | "The Builder Factory can only be registered once!" | `AddSkail`/`UseSkail` chamado duas vezes no processo | Procurar chamadas duplicadas; em testes, dois `ServiceProvider` | Registrar uma vez por processo | | "StateMachine not registered." | Método decorado não descoberto: assembly sem atributo, método não `async`, assinatura errada | A mensagem aparece no log ao disparar a function | Conferir atributo, `async`, `SkailTask` | | `Manifest workload ... does not match ...` (TypeScript) | `SKAIL_WORKLOAD` diferente do `--workload` usado no `skail build` | Comparar a variável com o comando de build | Gerar o build de novo com o mesmo `nome:versao` | | Build falha com um erro SKAIL001 a SKAIL006 | Assinatura fora das regras ou uso que quebra o replay | Mensagem do compilador | [Regras do analyzer](/referencia/sdk-csharp/regras-do-analyzer.md) | | Runtime não conecta ao skail | `SKAIL_SIDECAR` errado (host, porta, esquema), rede, ou indisponibilidade | Log da aplicação; testar acesso ao endereço a partir do host | Conferir a variável; ver [Suporte e status](/opere/suporte-e-status.md) | | `Unauthenticated` no log | `SKAIL_KEY` vazia, inválida ou revogada; `SKAIL_NAMESPACE` de outro environment | Comparar com a tela do environment | Corrigir; ver [Chaves](/opere/configurar-e-hospedar/chaves.md) | | `ResourceExhausted` no log | Limite atingido no skail | Recorrência no log | Reduzir carga; ver [Limites e cotas](/referencia/limites-e-cotas.md) | ## O trigger não funciona | Sintoma | Causa provável | Como confirmar | O que fazer | | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 com `missing_headers` | Falta um dos três headers: `Authorization`, `skail-key` ou `Skail-namespace` | Ver os headers que o chamador envia; a resposta traz `"error":"missing_headers"` e o `message` (por exemplo, `Authorization header is required.`) | Enviar os três headers. [Autenticação e headers](/referencia/api-http/autenticacao.md) | | 400 com `invalid_body` | Id do trigger (último segmento do caminho) não é um GUID, corpo não é array ou argumento não desserializa | A resposta traz `"error":"invalid_body"` e o `message` (por exemplo, `Request body field "taskId" must be a valid GUID.`) | Usar um GUID como id, gerado uma vez e guardado junto do id de negócio; corrigir o corpo (array na ordem da assinatura) | | 401 ou 403 | `Authorization`, `skail-key` ou `Skail-namespace` errados, ou de outro environment | Comparar headers com a tela do environment | Corrigir. [Autenticação e headers](/referencia/api-http/autenticacao.md) | | 2xx, nada no Monitor | URL base, chave e namespace de outro environment (a chamada foi aceita lá) | Procurar no Monitor do outro environment | Usar a URL base, a chave e o namespace do environment certo | | 2xx, aparece no Monitor, não executa (Na fila) | Nenhuma aplicação rodando com esse `SKAIL_WORKLOAD` | Log da aplicação; `SKAIL_WORKLOAD` | Subir a aplicação ou corrigir a variável | | 2xx, execução parada em Na fila com a aplicação rodando | `workload`, `versao` ou `funcao` do caminho não batem com o que a aplicação publica: `SKAIL_WORKLOAD` diferente do usado no trigger, método renomeado | Comparar o caminho do trigger com o `SKAIL_WORKLOAD` da aplicação e o nome do método | Corrigir o caminho ou a variável. Ver [Versionamento](/construa/conceitos/versoes-com-execucoes-em-andamento.md) | | 2xx, execução reentregue sem parar antes de entrar na function, com espera cada vez maior e sem virar falha (C#) | Enum mandado como texto no argumento do trigger (`"Aprovado"` em vez do número do membro, como `0`) | Comparar o corpo do trigger com o tipo do argumento na assinatura da function | Mandar o enum como número no JSON; se quem dispara manda texto, usar um campo `string` no tipo. Ver [Passar dados entre função e commands](/construa/como-fazer/passar-dados-entre-funcao-e-commands.md) | ## A execução não anda | Sintoma | Causa provável | Como confirmar | O que fazer | | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Aguardando evento há muito tempo | Nome ou instance id divergentes entre `WaitForEvent` e fire; fire enviado a outro namespace; webhook do parceiro não chegou | Monitor mostra nome e id esperados; comparar com o fire | Corrigir no `WaitForEvent` e no fire; disparar o fire manualmente por cURL se for o caso. [Eventos externos](/construa/conceitos/eventos-externos-e-correlacao.md) | | Aguardando evento sem prazo definido | Espera sem `WhenAny` com `Delay` | Código da function | Adicionar prazo; para a execução atual, disparar o evento ou aceitar a espera. [Como esperar com timeout](/construa/como-fazer/esperar-um-evento-com-prazo.md) | | Execução não retoma no horário do Delay | Nenhuma instância da aplicação rodando quando o prazo venceu; indisponibilidade | Estado Na fila após o prazo; log da aplicação | Subir/escalar a aplicação; a retomada acontece ao voltar | | Delay retoma antes do prazo, ou depois sem a aplicação ter ficado fora; horários do Monitor deslocados | Relógio da máquina que roda a aplicação fora da hora certa | Comparar a hora da máquina com uma fonte de hora; os comandos de cada sistema estão em [Relógio dos servidores](/opere/configurar-e-hospedar/relogio-dos-servidores.md) | Ligar a sincronização por NTP | | Na fila por muito tempo | Processos de menos, aplicação fora, ou todas as vagas ocupadas: cada processo processa até `SKAIL_MAX_PARALLEL_TASKS` execuções ao mesmo tempo (padrão 1) | Log; réplicas; valor de `SKAIL_MAX_PARALLEL_TASKS`; duração dos commands no Monitor | Aumentar `SKAIL_MAX_PARALLEL_TASKS` ou escalar réplicas. Ver [Variáveis de ambiente do runtime](/referencia/variaveis-de-ambiente-do-runtime.md) | ## A execução falha | Sintoma | Causa provável | Como confirmar | O que fazer | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Falha com exceção do seu command | Serviço externo fora além do `retryCount`; dado inválido; bug | Exceção e passo na linha do tempo | Corrigir a causa e retomar. [Retomada manual](/opere/retomada-manual-de-execucoes-falhas.md) | | `SkailNonDeterministicException` | Relógio, aleatoriedade, I/O ou `Task.*` na function; ou fluxo alterado com execuções em andamento (após deploy) | Comparar o código com a linha do tempo; ver se houve deploy | Corrigir o código ou publicar a versão compatível; retomar. [Determinismo e replay](/construa/conceitos/replay-e-determinismo.md) | | `SkailNonDeterministicException` com `Expected event type '...' (uri: ...) but replayed event has type '...' (uri: ...)` (C#), ou `SkailNonDeterministicError` com `Event N expected ..., but history contains ... at index N.` (TypeScript) | Na retomada, o código chama um passo diferente do que está no histórico naquela posição. A primeira parte da mensagem é o que o código chama agora; a segunda é o que foi gravado. Quase sempre é um `await` incluído, removido ou trocado de lugar numa function com execuções em andamento, publicado com o mesmo `SKAIL_WORKLOAD` | Procurar os dois métodos da mensagem no código e no deploy mais recente | Volte a publicar o código anterior com o mesmo `SKAIL_WORKLOAD` e retome as execuções que falharam ([Retomada manual](/opere/retomada-manual-de-execucoes-falhas.md)). Publique a mudança numa versão nova do workload, ou num método novo, e mantenha a anterior rodando até as execuções em andamento terminarem. [Versionamento](/construa/conceitos/versoes-com-execucoes-em-andamento.md) | | `NotSupportedException` ("Specified method is not supported.") em `SkailTaskMethodBuilder.Create()` (C#) | Método `async SkailTask` sem `[SkailFunction]` nem `[SkailCommand]` chamado pela function, como um helper privado; método decorado numa classe declarada dentro de outra classe; ou o pacote de build (`Skail.Platform.Runtime.Build`) não rodou na compilação | Na pilha da exceção, veja o método logo abaixo de `SkailTaskMethodBuilder.Create()`. Sem atributo, é o helper. Com atributo, confira se a classe dele está dentro de outra classe e se o pacote de build está no projeto | Helper: escrever o trecho no corpo da function ou fazer dele uma `[SkailFunction]` pública e de instância, que roda como function filha ([Antipadrões, item 32](/construa/como-fazer/padroes-e-antipadroes/antipadroes-o-que-nao-fazer-e-por-que.md)). Classe aninhada: declarar a classe direto no namespace. Build: refazer o build com o pacote presente | | Falha de negócio retentada várias vezes | Recusa lançada como exceção num command com retry ligado | Command com N tentativas iguais | Devolver resultado em vez de exceção, ou `retryCount: 0` e tratar na function. [Falhas, retries e idempotência](/construa/conceitos/retries-e-idempotencia.md) | | Command executado duas vezes no sistema externo | Falha entre a operação externa e a gravação do resultado, sem chave de idempotência | Duas chamadas no sistema externo, um passo no Monitor | Chave de idempotência. [Como escrever commands idempotentes](/construa/como-fazer/escrever-commands-idempotentes.md) | | Function reentregue 15 vezes após um command esgotar | Exceção do command não capturada na function | Linha do tempo com repetições | Capturar e decidir (compensar, marcar pendente). [Como tratar erros](/construa/como-fazer/tratar-erros-e-desfazer-passos.md) | | `catch` por tipo entra na primeira vez e falha depois da retomada (com `retryCount: 0`), ou nunca entra (com retry ligado); log da aplicação com `Exception thrown by user code cannot be persisted to durable state` (C#) | Classe de exceção sem construtor com um único parâmetro `string` que recebe a mensagem. O runtime não consegue reconstruí-la a partir do histórico e entrega uma `SkailException` no lugar | Procurar a mensagem no log da aplicação; conferir os construtores da classe de exceção | Dar à classe o construtor `(string message)`. Ver [Como tratar erros e compensar](/construa/como-fazer/tratar-erros-e-desfazer-passos.md) | | `instanceof` reconhece o erro na primeira falha e deixa de reconhecer depois da retomada (TypeScript) | Classe de erro vinda de pacote npm. O `skail build` registra só as classes declaradas no projeto, e na retomada esse erro volta sem a classe do pacote, com o `name` preservado | Ver o `name` do erro no log | Comparar só pelo `name`, sem `instanceof Error`, que também deixa de valer para esse erro na retomada; se o pacote não define o `name`, comparar pelo `code` ou capturar o erro no command e lançar uma classe declarada no projeto. Ver [Como tratar erros e compensar](/construa/como-fazer/tratar-erros-e-desfazer-passos.md) | | Execução C# termina em erro ao retomar depois de um fire, sem linha de erro no log da aplicação | Enum mandado como texto no payload do fire (`"Aprovado"` em vez do número do membro, como `0`), inclusive num fire que sai de TypeScript com união de strings ou de outro sistema que manda texto | Comparar o payload do fire com o tipo esperado no `WaitForEvent` | Mandar o enum como número no JSON; se quem dispara manda texto, usar um campo `string` no tipo. Ver [Passar dados entre função e commands](/construa/como-fazer/passar-dados-entre-funcao-e-commands.md) | | Execução C# quebra na primeira retomada depois de registrar um conversor de enum no `UseSkail`, em functions com command que devolve enum | `JsonStringEnumConverter` registrado no `UseSkail` | Procurar o conversor na configuração do `UseSkail` | Tirar o conversor e publicar. As execuções que já gravaram o enum como texto não se recuperam com a mudança. Ver [Passar dados entre função e commands](/construa/como-fazer/passar-dados-entre-funcao-e-commands.md) | ## Testes e depuração | Sintoma | Causa provável | O que fazer | | -------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Teste TypeScript termina com `status: "hibernated"` | Function chegou a um delay ou a uma espera ainda não satisfeita | Avançar com `platform.complete(...)` ou `platform.signal(...)`. Ver [Testar seus fluxos](/construa/como-fazer/testar-seus-fluxos.md) | | Teste TypeScript: `instanceof` falha depois da retomada | Classe de erro fora de `errorTypes` no `createSkailWorker` | Passar a classe em `errorTypes`. Ver [Testar seus fluxos](/construa/como-fazer/testar-seus-fluxos.md) | | Time Travel Debug diverge com `SkailNonDeterministicException` | Código local diferente do que gerou a captura | Usar a mesma versão. [Como depurar com Time Travel Debug](/construa/como-fazer/depurar-com-time-travel-debug.md) | | Logs duplicados de uma function | Replay reexecuta o corpo | Esperado; use `TaskId` no escopo; logue em command o que não pode repetir | ## Antes de abrir um chamado Tenha à mão: * TaskId da execução; * workload e versão; * environment; * horário; * a exceção do Monitor; * o trecho relevante do log da aplicação. Ver [Suporte e status](/opere/suporte-e-status.md). ## Próximos passos
:bell:Monitoramento e alertasPara detectar antes do sintoma.Monitoramento e alertas
:circle-exclamation:ExceçõesPara a referência das mensagens.Exceções