---
title: 'Troubleshooting: Compile errors'
path: troubleshooting/compile-errors
status: published
---

# Troubleshooting: Compile errors

The compiler refuses bad flows with a `CompileError` carrying a list of human-readable diagnostics. Each one points at the specific node/edge/field that's wrong.

The canvas's Live Preview pane renders these inline as you type; CLI prints them to stderr.

## `edge 'edge_xyz': source node 'node_abc' has no output port 'out_typo'`

You renamed a port (or changed the node kind) but an edge still references the old port id.

**Fix:** Select the edge and update its `source.port` (or `target.port`). Or delete the edge and re-draw.

In the canvas, dangling edges are highlighted red on the canvas + the property panel lists the dangling reference.

## `llm_role validation failed: node 'node_xyz': llm_role='fastt' is not declared`

An LLM node references a role that isn't in the flow's model registry. Usually a typo.

**Fix:** Click the LLM node → Model role dropdown. The orphan role renders in red with a pointer. Either pick an existing role or add `fastt` to Flow → Models.

## `flow has no entry-point node`

No `entry_api` / `entry_webhook` / `entry_schedule` on the canvas.

**Fix:** Drag one from the palette. Every flow needs an entry.

Note: there is no `entry_chat`. If you want the flow reachable as a chat model, use an `entry_api` and toggle Flow → Publish as chat model.

## `cycle detected: node_a -> node_b -> node_a`

The control-flow graph has a cycle. Loops are fine, but they need to be expressed via a `logic_loop` node (which compiles to `foreach` or `while` blocks), not via raw back-edges between arbitrary nodes.

**Fix:** Remove the back-edge. If you actually want iteration, drag a Loop node and put the looped body inside its branch.

## `while loop missing max_iterations`

`logic_loop` with style `while` requires `max_iterations` — ScaiCore needs a compile-time upper bound to refuse runaway loops.

**Fix:** Click the loop node, set Max iterations to a number (1000 is a reasonable starting point).

## `plugin call 'scaidrive.search': missing required arg 'path'`

The compiler's per-plugin signature check caught a missing arg.

**Fix:** Click the tool_plugin node, fill in the required arg under `args`.

## `unknown node kind 'entry_telepathy'`

The flow JSON has a node with a `type` not in the enum. Usually from a hand-edited JSON or an imported third-party flow.

**Fix:** Change `type` to one of the supported kinds. See [Node kinds reference](../reference/node-kinds).

## `conditional edge missing condition`

An edge has `type: "conditional"` but no `condition` string.

**Fix:** Set a condition (the smallest valid one is `"true"`, but that defeats the purpose). For decision nodes, the property panel's Branches list lets you edit each conditional edge's condition inline.

## How to read a compile error

The CompileError exception's `.errors` attribute is a list of strings. Each string starts with the node/edge id it points at:

```text
edge 'edge_5': source node 'node_classify' has no output port 'out_amout'
edge 'edge_7': target node 'node_provision' has no input port 'in'
node 'node_review': llm_role='primary' is not declared in flow.config.core_identity.models
```

Each gets fixed independently. There's no error-rollup — fix them all, re-compile, repeat.