> 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/referencia/sdk-csharp/excecoes.md). # Exceções As exceções que o SDK pode lançar no seu código, quando acontecem e o que fazer com cada uma. O tipo da exceção e a mensagem dela indicam a causa. ## Exceções do SDK | Exceção | Quando acontece | O que fazer | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SkailNonDeterministicException` | O replay divergiu do histórico da execução: o passo que o código quer executar não é o que foi registrado naquela posição (índice diferente, ou tipo de evento e endereço do método diferentes) | Corrigir o código. Nunca capturar. Causas: relógio, aleatoriedade ou I/O na function; `Task.Delay`/`Task.WhenAll` na function; fluxo alterado com execuções em andamento; método renomeado. Ver [Determinismo e replay](/construa/conceitos/replay-e-determinismo.md) e [Versionamento](/construa/conceitos/versoes-com-execucoes-em-andamento.md) | | `SkailException` | Erro na comunicação com o skail (buscar trabalho, gravar um passo, confirmar). Também chega à function no lugar de uma exceção do command que o runtime não conseguiu reconstruir a partir do histórico | O runtime já retenta as falhas transitórias antes de lançar. Se chegar ao seu código, leia a mensagem da exceção: em geral é configuração (chave ou namespace errados) ou limite atingido. Não capture para seguir em frente; corrija a causa. Se o log da aplicação mostra "Exception thrown by user code cannot be persisted to durable state", a exceção lançada no command não pode ser reconstruída: dê à classe dela um construtor `(string message)`. Ver [Como tratar erros e compensar](/construa/como-fazer/tratar-erros-e-desfazer-passos.md) | | `SkailCanceledException` | A comunicação com o skail estourou o tempo ou foi cancelada. É um tipo de `SkailException`; a execução em si não é cancelada | Deixe propagar, como `SkailException` | | `SkailEventStoreException` | Falha ao registrar um passo da execução no skail | Interna; o runtime trata. Se aparecer no seu log de forma recorrente, é sintoma de indisponibilidade; ver [Troubleshooting](/opere/troubleshooting.md) | {% hint style="info" %} Exceções lançadas pelo seu próprio código dentro de um command seguem a regra de retry: retentadas até `retryCount`, depois lançadas dentro da function. Com `retryCount: 0`, a function recebe a exceção na primeira falha. Para a function receber a exceção com o tipo original, inclusive depois de uma retomada, a classe precisa de um construtor com um único parâmetro `string`, que recebe a mensagem. `ArgumentException`, `ArgumentNullException` e `ArgumentOutOfRangeException` voltam com o tipo original, mas a mensagem e o `ParamName` mudam depois da retomada; se a function usa esses valores, capture a exceção no command e relance como uma classe própria. Ver [Falhas, retries e idempotência](/construa/conceitos/retries-e-idempotencia.md) e [Como tratar erros e compensar](/construa/como-fazer/tratar-erros-e-desfazer-passos.md). {% endhint %} ## Mensagens de erro do runtime Não são exceções tipadas do SDK, mas aparecem no log e têm causa conhecida: | Mensagem | Causa | Correção | | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | "There is not Skail runtime available!" | Método skail chamado sem `builder.UseSkail()`/`services.AddSkail()` no processo | Chame `UseSkail()` ou `AddSkail()` uma vez. Ver [Configuração do host](/referencia/sdk-csharp/configuracao-do-host.md) | | "Specified method is not supported." (`NotSupportedException` em `SkailTaskMethodBuilder.Create()`) | Método `async SkailTask` sem `[SkailFunction]` nem `[SkailCommand]`, como um helper privado; método decorado numa classe declarada dentro de outra classe; ou o pacote `Skail.Platform.Runtime.Build` não rodou na compilação | Ver [Troubleshooting](/opere/troubleshooting.md) e o item 32 de [Antipadrões](/construa/como-fazer/padroes-e-antipadroes/antipadroes-o-que-nao-fazer-e-por-que.md) | | "The Builder Factory can only be registered once!" | `AddSkail`/`UseSkail` chamado mais de uma vez no mesmo processo (dois `ServiceProvider`) | Um só registro por processo; em testes, isole | | "StateMachine not registered." | Método decorado não descoberto: assembly sem o atributo, método não `async`, assinatura errada, `AddSkail` antes do assembly carregar | Confira atributo, `async`, retorno `SkailTask` | ## O que capturar e o que não Capture, na function, as exceções dos seus próprios commands depois que esgotaram o retry, para compensar ou decidir. Não capture `SkailNonDeterministicException` nem `SkailException` de forma genérica; use `catch (Exception ex) when (ex is not SkailNonDeterministicException and not SkailException)` se precisar de um catch amplo. Dê a toda exceção lançada num command o construtor `(string message)`, para ela chegar ao filtro com o próprio tipo. Ver [Como tratar erros e compensar](/construa/como-fazer/tratar-erros-e-desfazer-passos.md). ## Veja também [Troubleshooting](/opere/troubleshooting.md), [Falhas, retries e idempotência](/construa/conceitos/retries-e-idempotencia.md), [Regras do analyzer](/referencia/sdk-csharp/regras-do-analyzer.md).