Kailash Rust SDK Error Troubleshooting

Runtime errors that remain are returned via Result<T, E> and must be handled with ? or match.

Error Type Hierarchy

RuntimeError
  |-- BuildFailed { source: BuildError }
  |     |-- UnknownNodeType { type_name }
  |     |-- DuplicateNodeId { node_id }
  |     |-- InvalidConnection { source_node, source_output, target_node, target_input, reason }
  |     |-- CycleDetected { nodes }
  |     |-- DisconnectedGraph { components }
  |     |-- NodeCreationFailed { node_id, type_name, source: NodeError }
  |     |-- EmptyWorkflow
  |-- NodeFailed { node_id, source: NodeError }
  |     |-- MissingInput { name }
  |     |-- InvalidInput { name, expected, got }
  |     |-- ExecutionFailed { message, source }
  |     |-- Timeout { duration }
  |     |-- ResourceLimit { resource, limit }
  |     |-- Internal { message }
  |-- Timeout { duration }
  |-- Cancelled
  |-- Internal { message }

Reference Documentation

Critical Errors

Missing .build() Call (Compile-Time)

• error-missing-build - Forgot to call .build(&registry)?
  • Symptom: Compile error: expected &Workflow, found WorkflowBuilder
  • Cause: Passing builder directly to runtime.execute()
  • Solution: Always call builder.build(&registry)? before execution
  • Pattern: let workflow = builder.build(&registry)?;

Nexus Blocking (Async Runtime)

• error-nexus-blocking - Nexus/axum handler blocks
  • Symptom: axum handler hangs, tokio panic, request timeout
  • Cause: Using execute_sync() inside an async handler
  • Solution: Use runtime.execute(&workflow, inputs).await? in async contexts
  • Prevention: Never call sync methods inside async functions

Connection & Parameter Errors

Connection Parameter Errors

• error-connection-params - Invalid connections
  • Symptom: BuildError::InvalidConnection at build time
  • Cause: Wrong 4-parameter order in builder.connect()
  • Solution: Use builder.connect("source", "output", "target", "input")
  • Common mistake: Swapping source_output and target positions

Parameter Validation Errors

• error-parameter-validation - Missing required inputs
  • Symptom: NodeError::MissingInput or NodeError::InvalidInput at runtime
  • Cause: Missing or wrong-typed node parameters
  • Solution: Provide via config ValueMap, connections, or runtime inputs
  • 3 methods: Config, connections, runtime inputs

Runtime Errors

Runtime Execution Errors

• error-runtime-execution - Runtime failures
  • Symptom: RuntimeError::NodeFailed, RuntimeError::Timeout
  • Cause: Node failures, timeouts, wrong runtime usage
  • Solutions: Check error chain, configure timeouts, use correct async/sync method
  • Debug: Match on RuntimeError variants, walk .source() chain

Cyclic Workflow Errors

Cycle Detection Errors

• error-cycle-convergence - Cycle issues
  • Symptom: BuildError::CycleDetected or infinite loop at runtime
  • Cause: Cycles without enable_cycles(true), no convergence condition
  • Solution: Enable cycles explicitly, use LoopNode with max_iterations
  • Pattern: builder.enable_cycles(true) before .build()

DataFlow Errors

DataFlow Type Errors

• error-dataflow-template-syntax - Type mismatches
  • Symptom: NodeError::InvalidInput on DataFlow-generated nodes
  • Cause: Wrong Value variant for model field type
  • Solution: Match Value types to model field types (i64 -> Value::Integer, etc.)
  • Pattern: Use connections for dynamic values between nodes

Quick Error Reference

Error by Symptom

Error Prevention Checklist

Before Building Workflow:

• Called .build(&registry)? on WorkflowBuilder?
• Used ? to propagate the BuildError?
• All connect() calls use 4 parameters in correct order?
• All required node parameters provided in config ValueMap?
• Cyclic workflows have enable_cycles(true) set?
• All node types registered in NodeRegistry?

Before Executing Workflow:

• Using execute().await? in async contexts (axum, tokio::main)?
• Using execute_sync() only in sync contexts (CLI, scripts)?
• RuntimeConfig::timeout set appropriately?
• Error result handled with ? or match?

Common Error Patterns

1. Missing .build() (Compile-Time)

// :x: WRONG (compile error)
let mut builder = WorkflowBuilder::new();
builder.add_node("EchoNode", "echo", ValueMap::new());
let result = runtime.execute(&builder, ValueMap::new()).await?;

// :white_check_mark: CORRECT
let mut builder = WorkflowBuilder::new();
builder.add_node("EchoNode", "echo", ValueMap::new());
let workflow = builder.build(&registry)?;
let result = runtime.execute(&workflow, ValueMap::new()).await?;

2. Nexus Blocking (Async/Sync Mismatch)

// :x: WRONG (panics or deadlocks in async handler)
async fn handle(State(rt): State<Arc<Runtime>>) -> impl IntoResponse {
    let result = rt.execute_sync(&workflow, inputs);  // Blocks async runtime!
}

// :white_check_mark: CORRECT (async in async)
async fn handle(State(rt): State<Arc<Runtime>>) -> impl IntoResponse {
    let result = rt.execute(&workflow, inputs).await?;
}

3. Connection Parameter Order

// :x: WRONG (swapped parameters)
builder.connect("node1", "node2", "result", "input");

// :white_check_mark: CORRECT (source, output, target, input)
builder.connect("node1", "result", "node2", "input");

4. Cycle Detection

// :x: WRONG (cycle without enable_cycles)
builder.connect("a", "out", "b", "in");
builder.connect("b", "out", "a", "in");  // Cycle!
let wf = builder.build(&registry)?;  // BuildError::CycleDetected

// :white_check_mark: CORRECT (enable cycles explicitly)
builder.enable_cycles(true);
builder.connect("a", "out", "b", "in");
builder.connect("b", "out", "a", "in");
let wf = builder.build(&registry)?;  // OK

5. DataFlow Type Mismatch

// :x: WRONG (String where Integer expected)
builder.add_node("OrderCreateNode", "create", ValueMap::from([
    ("customer_id".into(), Value::String("42".into())),
]));

// :white_check_mark: CORRECT (matching Value variant)
builder.add_node("OrderCreateNode", "create", ValueMap::from([
    ("customer_id".into(), Value::Integer(42)),
]));

Debugging Strategies

Step 1: Check Error Type

• Compile error? Fix the Rust code -- type system is guiding you
• BuildError? Fix workflow construction (nodes, connections, types)
• RuntimeError? Fix execution (inputs, timeouts, node logic)
• NodeError? Fix individual node configuration or inputs

Step 2: Walk the Error Chain

use std::error::Error;

if let Err(e) = runtime.execute(&workflow, inputs).await {
    eprintln!("Error: {e}");
    let mut source = e.source();
    while let Some(cause) = source {
        eprintln!("  Caused by: {cause}");
        source = cause.source();
    }
}

Step 3: Test Components

• Build and execute a minimal workflow with one node
• Add nodes incrementally to isolate the failing one
• Inspect result.results.get("node_id") for output structure

Step 4: Check Source Code

• Error types: crates/kailash-core/src/error.rs
• Workflow builder: crates/kailash-core/src/workflow.rs
• Runtime: crates/kailash-core/src/runtime.rs
• Node implementations: crates/kailash-nodes/src/
• CLAUDE.md for essential patterns

CRITICAL Debugging Tips

1. ALWAYS call .build(&registry)? on WorkflowBuilder before execution
2. NEVER use execute_sync() inside async contexts (axum handlers, tokio::main)
3. ALWAYS handle Result values with ? or explicit error matching
4. NEVER ignore BuildError -- it means your workflow graph is invalid
5. ALWAYS verify connection parameter order: source, output, target, input

Related Skills

• 01-core - Core SDK patterns
• 02-dataflow - DataFlow specifics
• 03-nexus - Nexus/axum specifics
• 13-testing-strategies - Testing patterns
• 15-code-templates - Working code templates

CI Debugging Patterns

Documentation job fails (-D warnings)

CI runs RUSTDOCFLAGS="-D warnings" cargo doc --workspace --exclude kailash-ruby --exclude kailash-python --no-deps. Intradoc links like [TypeName] fail unless the type is in scope — use fully qualified: [crate::module::TypeName].

Test job fails (doc-tests)

CI runs cargo test --workspace which includes doc-tests. Common failures:

• Non-exhaustive match: New enum variant added but doc example match not updated (e.g., CallerEvent::ToolCallDelta)
• Result API change: Constructor changed to return Result but doc example doesn't use ? (e.g., WorkerAgent::new())
• Signature change: Args added/removed but doc example uses old count (e.g., SupervisorAgent::new() now 4 args)

Cargo Deny fails

Usually corrupt advisory DB cache on self-hosted runner (panics on RUSTSEC-0000-0000.md). Fix: re-run the job via gh run rerun <run-id> --job <job-id>.

CI traps

• cargo check --workspace fails on magnus 0.8.2 — always --exclude kailash-ruby (#247)
• kailash-python rustdoc ICE on numpy ToPyArray — excluded from CI doc build
• nightly fmt required (cargo +nightly fmt) — stable fmt produces different output

Support

For error troubleshooting, consult:

• build-fix agent - Fix Rust compilation errors with minimal changes
• dataflow-specialist - DataFlow-specific patterns
• nexus-specialist - Nexus/axum integration debugging
• testing-specialist - Test debugging