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.

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:

1
2
3

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.