> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/troubleshooting.md).
# Resolução de Problemas do Rules Engine
Resolva erros de regras no Kilo IoT — nós em falta, CEL inválido, ligação de boundary, limites de implementação.
Esta página cobre os problemas mais comuns que encontrará ao criar, implementar e gerir regras de automatização — erros de validação da compilação, problemas de execução e limites da plataforma.
## Erros de compilação
Quando clicar **Guardar e Compilar** na Barra lateral dos resultados da compilação, a plataforma valida todo o diagrama antes de produzir um artefacto. Se a validação falhar, as mensagens de erro aparecem na barra lateral. Aqui estão os erros que poderá ver, o que os causa e como corrigi-los.
| Erro | Causa | Correção |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Evento de início em falta | O diagrama não tem nenhum nó Evento de Início | Arraste um Evento de Início da paleta para a tela. Toda regra tem de começar com exatamente um Evento de Início. |
| Evento de fim em falta | O diagrama não tem nenhum nó Evento de Fim | Adicione pelo menos um Evento de Fim. Cada caminho de execução tem de terminar num Evento de Fim. |
| Vários eventos de início | Existe mais do que um Evento de Início na tela | Remova os Eventos de Início extra. Uma regra pode ter apenas um ponto de entrada. |
| Sem fluxo de saída | Um nó não tem nenhuma seta a sair dele (e não é um Evento de Fim) | Ligue o nó à etapa seguinte no fluxo de trabalho. Todo nó não terminal precisa de um fluxo de saída. |
| Evento de início sem fluxo de saída | O Evento de Início não está ligado a nenhum nó | Desenhe um fluxo sequencial do Evento de Início para o primeiro nó de processamento na sua regra. |
| Condição em falta | Uma ramificação de um Gateway Exclusivo não tem nenhuma expressão de condição CEL atribuída | Abra as propriedades do gateway e adicione uma expressão CEL a cada ramificação não predefinida. Uma ramificação deve ser marcada como predefinida (não é necessária nenhuma condição para a predefinida). |
| Expressão inválida | Uma expressão CEL contém um erro de sintaxe | Verifique se a expressão tem parênteses por fechar, aspas em falta à volta das strings ou operadores incorretos. Veja [Referência CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) para a sintaxe válida. |
| A condição tem de devolver bool | Uma expressão de condição do gateway devolve um valor não booleano | As condições do gateway têm de ser avaliadas como `verdadeiro` ou `falso`. Use operadores de comparação (`>`, `<`, `==`, `!=`, `>=`, `<=`) ou operadores lógicos (`&&`, `\|\|`, `!`). |
| Evento de fronteira não ligado | Existe um Evento de Erro de Fronteira na tela, mas não está ligado a um nó de tarefa | Arraste o Evento de Erro de Fronteira para uma Tarefa de Script, Definir Alarme ou nó de Enriquecimento. Tem de estar visualmente ligado à margem de uma tarefa. |
| Destino de saída do evento de fronteira | O fluxo de saída de um Evento de Erro de Fronteira aponta para algo que não é uma tarefa nem um Evento de Fim | Redirecione o caminho de erro para uma tarefa (a etapa de tratamento) ou para um Evento de Fim. |
| O fluxo predefinido não pode ter uma condição | O fluxo marcado como predefinido do gateway ainda tem uma condição CEL | Remova a condição do fluxo predefinido. O fluxo predefinido é executado precisamente quando mais nada corresponde, por isso não tem uma expressão própria. |
| O gateway tem de dividir ou fundir | Um Gateway Exclusivo tem exatamente um fluxo de entrada e um de saída | Um gateway tem de tomar uma decisão (dois ou mais fluxos de saída) ou reunir caminhos novamente (dois ou mais de entrada). Um gateway de passagem não faz nada — elimine-o e ligue os nós diretamente. |
| ID de elemento duplicado | Dois elementos na tela partilham um identificador | Normalmente, é o resultado de importar ou editar externamente um diagrama. Elimine e volte a adicionar um dos dois elementos. |
| Parâmetro de entrada ou saída não suportado | O parâmetro de Entrada ou Saída de um nó não é uma expressão CEL | As Entradas e Saídas aceitam apenas expressões CEL. Insira novamente o parâmetro no painel de propriedades. |
| Parâmetro de Execute Command inválido | Um nó Execute Command tem um parâmetro sem nome, sem valor ou com um nome usado duas vezes | Abra o painel de propriedades do nó e dê a cada parâmetro um nome único e um valor ou expressão. |
| Tipo de elemento desconhecido | Existe um nó não reconhecido na tela | Remova o elemento desconhecido e substitua-o por um tipo de nó suportado da paleta. Isto pode acontecer se um diagrama tiver sido importado ou modificado externamente. |
### A resolver erros de compilação
1. Leia a mensagem de erro na Barra lateral dos resultados da compilação — identifica o problema e, muitas vezes, o nó específico.
2. Feche a barra lateral e corrija o problema na tela.
3. Clique em **Compilar** novamente para revalidar.
Podem aparecer vários erros em simultâneo. Corrija-os todos antes de tentar compilar novamente.
## Problemas comuns
### "Criei um acionador, mas nada acontece"
Um acionador guardado apenas monitoriza a sua condição. Não contém um alarme, comando ou outra resposta, e não é anexado automaticamente a uma regra.
**O que fazer:**
1. Volte ao separador **Regras** e crie ou edite a regra que deve responder.
2. Selecione o Evento de Início, clique no ícone do lápis e defina **Fonte de início** como **Condição do acionador**.
3. Selecione o acionador guardado e clique em **Guardar** na parte inferior do painel do Evento de Início.
4. Adicione os nós de resposta e depois guarde a regra a partir da barra de ferramentas do editor.
5. Compile a regra e implemente o seu artefacto a partir do separador **Artefactos** .
Consulte [De um acionador para uma regra em execução](/kilo-docs-pt/kilo-iot-server/rules-engine/triggers.md#from-a-trigger-to-a-running-rule) para o fluxo de trabalho completo.
### "O meu acionador não aparece no Evento de Início"
O **Condição do acionador** campo aparece apenas depois de alterar a propriedade do Evento de Início **Fonte de início** de **Leitura do sensor** como **Condição do acionador**. Lista os acionadores guardados para a organização atual e, de momento, carrega apenas a primeira página de resultados.
**O que fazer:**
* Confirme que o acionador foi criado na mesma organização que a regra.
* Confirme que **Condição do acionador** está selecionado como a Fonte de início.
* Se o acionador existir mas estiver para além da primeira página, ainda não pode ser selecionado a partir deste campo.
### "A regra está bloqueada e não a consigo editar"
Outro membro da equipa está atualmente a editar a regra. O ícone de bloqueio na linha da regra mostra quem detém o bloqueio e quando expira.
**O que fazer:**
* Aguarde até o bloqueio expirar. A expiração do bloqueio é mostrada na interface na dica de ferramenta do bloqueio.
* Contacte a pessoa que detém o bloqueio e peça-lhe para guardar e sair.
* Se a pessoa que detém o bloqueio não estiver disponível e você for o proprietário da organização, pode forçar o desbloqueio da regra a partir da lista de Regras. Veja [Editar Bloqueios e Transferências de Equipa](/kilo-docs-pt/kilo-iot-server/rules-engine/edit-locks-and-team-handoffs.md) para mais detalhes.
### "A compilação foi bem-sucedida, mas a regra não está em execução"
Compilar e implementar são passos separados. Uma compilação bem-sucedida cria um artefacto, mas o artefacto não é implementado automaticamente.
**O que fazer:**
1. Vá para o separador **Artefactos** na página do Motor de Regras.
2. Encontre a compilação que acabou de criar.
3. Clique em **Implementar** para iniciar o processamento da regra a partir da sua fonte de sensor ou acionador selecionada.
### "A regra foi parada à força"
A plataforma monitoriza a saúde da execução. Se uma regra encontrar erros persistentes durante a execução, é parada automaticamente para evitar falhas em cascata. O artefacto mostra o estado **Parado à Força** (vermelho) no separador Artefactos.
**O que fazer:**
1. Abra a regra no editor e reveja a lógica.
2. Verifique se os sensores referidos ainda estão ativos e a reportar dados.
3. Verifique se todas as expressões CEL são válidas para as formas de dados reais que os seus sensores produzem.
4. Verifique os nós de Enriquecimento — o sensor de destino pode ter sido eliminado ou colocado offline.
5. Corrija o problema, crie um novo artefacto e implemente-o.
Consulte [Segurança de emergência](/kilo-docs-pt/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md#emergency-safety) para mais detalhes.
### "O Enriquecimento continua a falhar"
O nó de Enriquecimento obtém a leitura mais recente de outro sensor. Se esse sensor estiver offline, eliminado ou nunca tiver reportado dados, o enriquecimento falha.
**O que fazer:**
* Verifique se o sensor de destino existe e está ativamente a reportar dados.
* Anexe um **Evento de Erro de Fronteira** ao nó de Enriquecimento para que a regra trate a falha de forma graciosa em vez de parar completamente. Veja [Padrão 4: enriquecimento à prova de erro](/kilo-docs-pt/kilo-iot-server/rules-engine/automation-patterns.md#pattern-4-error-safe-enrichment).
### "A gravação automática falhou"
Uma interrupção de rede ou um problema temporário no servidor impediu a gravação automática.
**O que fazer:**
* Aparece uma caixa de diálogo com duas opções: **Tentar novamente** (tenta gravar outra vez) ou **Voltar para a regra** (regressa à lista de Regras sem guardar as alterações mais recentes).
* Tente **Tentar novamente** primeiro. Se falhar repetidamente, guarde manualmente usando o **Guardar** botão.
* Se a gravação manual também falhar, verifique a sua ligação à rede.
### "Não consigo restaurar uma regra do lixo"
A regra pode ter excedido a janela de retenção do lixo e ter sido eliminada permanentemente.
**O que fazer:**
* Verifique o separador **Lixo** Se a regra já não estiver listada, foi removida permanentemente e não pode ser recuperada.
* Se a regra ainda estiver no separador Lixo, mas a restauração falhar, verifique se a sua organização atingiu o limite de regras da subscrição. Restaurar uma regra conta para a quota de regras ativas.
### "Restaurou por engano a versão errada"
Restaurar uma versão não destrói nada. A restauração cria uma nova versão atual, e a versão anteriormente ativa é preservada no histórico.
**O que fazer:**
1. Abra o **Histórico** .
2. Encontre a versão que estava ativa antes da restauração acidental.
3. Veja-a (ícone de olho) e clique em **Restaurar esta versão** para a tornar novamente atual.
## Sessões de depuração
### "Iniciei uma sessão de depuração e nada acontece"
Uma sessão de depuração carrega a regra, coloca a execução no Evento de Início e espera por si. Não executa a regra por si só.
**O que fazer:**
1. Veja a parte inferior da tela para a barra de ferramentas de depuração. Ela flutua sobre o diagrama; não está na barra de cabeçalho ao lado de Guardar e Compilar.
2. Prima **Executar (F10)** para executar até ao primeiro ponto de interrupção ou ao fim, ou **Avançar um passo (F9)** para avançar um elemento.
3. Verifique se a sessão está ativa: o Evento de Início tem um contorno azul e o painel de depuração à direita lista as suas variáveis iniciais.
Consulte [Depurar Regras](/kilo-docs-pt/kilo-iot-server/rules-engine/debugging-rules.md#the-session-starts-paused).
### "Um elemento está contornado a vermelho"
Um contorno vermelho assinala o elemento que gerou o erro mais recente — não é um ponto de interrupção (um pequeno ponto vermelho acima do elemento) nem a posição atual (um contorno azul). Comece pela expressão nesse elemento.
**O que fazer:**
1. Abra as propriedades do elemento e leia a sua expressão.
2. Verifique se todos os nomes que usa existem no separador Variáveis. Uma expressão que leia `vars.RH` falha se nada chamado `RH` foi fornecido como contexto inicial ou produzido por um nó anterior.
3. Verifique o separador `vars.` prefixo está presente — `RH > 70` não é o mesmo que `vars.RH > 70`.
4. Verifique se a expressão devolve o tipo certo. Uma condição de gateway tem de produzir `verdadeiro` ou `falso`.
5. Cole a expressão em **Avaliar** no separador Watch para a testar contra o estado atual.
### "O gateway não tomou nenhuma ramificação"
Duas causas diferentes, com correções diferentes.
**Uma condição falhou ao ser avaliada.** Se alguma condição no gateway gerar erro — na maioria das vezes porque referencia uma variável que não existe — o gateway pára com erro e a regra não avança mais. Não **o faz** seguir para o fluxo predefinido. O gateway ficará contornado a vermelho; siga os passos acima.
**Nenhuma condição correspondeu e não há predefinição.** Se todas as condições devolveram falso e nenhum fluxo estiver marcado como predefinido, a execução não tem para onde ir. Abra o gateway, escolha o fluxo de reserva e clique em **Definir como predefinição**.
### "Os botões de depuração estão a cinzento"
Os controlos de passo estão disponíveis enquanto a sessão está em pausa. Estão desativados enquanto a regra está em execução, enquanto uma caixa de diálogo de Efeito Secundário aguarda uma resposta e depois de uma regra falhar ao carregar. Parar continua disponível em todos os momentos.
Se a regra falhou ao carregar, inicie uma nova sessão.
### "Os meus pontos de interrupção desapareceram"
Duas causas:
* **Usou Executar ignorando pontos de interrupção (F11).** Desliga todos os pontos de interrupção e deixa-os desligados durante o resto da sessão. Volte a ativá-los a partir do separador Pontos de interrupção.
* **O editor foi recarregado.** Os pontos de interrupção estão ligados aos elementos no diagrama carregado. Uma notificação indica quantos foram descartados para que os possa adicionar novamente.
### "A sessão terminou enquanto eu ainda estava a trabalhar"
Uma sessão de depuração dura 30 minutos, medidos a partir do momento em que começou. Avançar na regra não prolonga esse tempo. Receberá um aviso pouco antes de expirar; inicie uma nova sessão para continuar.
## Limites da subscrição
Cada plano de subscrição inclui um número máximo de regras de automatização ativas. Estes limites afetam várias operações:
* **Criar regras:** O **Adicionar Regra** o botão no separador Regras fica desativado quando a sua organização atinge o limite de regras. Uma mensagem explica que o limite foi atingido.
\- \*\*Restaurar do lixo:\*\* Restaurar uma regra eliminada conta como adicionar uma regra ativa. Se estiver no limite, a restauração não avançará. - \*\*Clonar regras:\*\* Clonar cria uma nova regra, que conta para o limite.
Para verificar a sua utilização atual e os limites do plano, visite as definições de subscrição da sua organização. Para aumentar o limite, atualize o seu plano ou remova regras de que já não precisa.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
