Common error patterns and troubleshooting guides for the Kailash Rust SDK including Nexus blocking issues, connection parameter errors, runtime execution errors, cycle detection problems, missing .build() calls, parameter validation errors, and DataFlow type errors. Use when encountering errors, debugging issues, or asking about 'error', 'troubleshooting', 'debugging', 'not working', 'hangs', 'timeout', 'validation error', 'connection error', 'runtime error', 'cycle detected', 'missing build', or 'DataFlow type'.
Comprehensive troubleshooting guides for common Kailash Rust SDK errors and issues.
Common error patterns and solutions for:
BuildError::InvalidConnection)RuntimeError)BuildError::CycleDetected).build(®istry)? calls (compile-time errors)NodeError::MissingInput, NodeError::InvalidInput)In Rust, many errors are caught at compile time rather than runtime:
| Error Category | Dynamic Language | Rust |
|---|---|---|
Missing .build() | Runtime TypeError |
| Compile error: type mismatch |
| Wrong method name | Runtime AttributeError | Compile error: method not found |
| Wrong arg count | Runtime TypeError | Compile error: argument count |
| Builder reuse after build | Silent bug | Compile error: use of moved value |
Runtime errors that remain are returned via Result<T, E> and must be handled with ? or match.
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 }
.build(®istry)?
&Workflow, found WorkflowBuilderruntime.execute()builder.build(®istry)? before executionlet workflow = builder.build(®istry)?;execute_sync() inside an async handlerruntime.execute(&workflow, inputs).await? in async contextsBuildError::InvalidConnection at build timebuilder.connect()builder.connect("source", "output", "target", "input")NodeError::MissingInput or NodeError::InvalidInput at runtimeRuntimeError::NodeFailed, RuntimeError::TimeoutRuntimeError variants, walk .source() chainBuildError::CycleDetected or infinite loop at runtimeenable_cycles(true), no convergence conditionbuilder.enable_cycles(true) before .build()NodeError::InvalidInput on DataFlow-generated nodesValue variant for model field type| Symptom | Error Type | Quick Fix |
|---|---|---|
| Compile: expected &Workflow | Missing .build() | Add builder.build(®istry)? |
| axum handler hangs | Nexus blocking | Use execute().await not execute_sync() |
| "invalid connection from..." | BuildError::InvalidConnection | Check 4-parameter order |
| "unknown node type" | BuildError::UnknownNodeType | Register node in NodeRegistry |
| "missing required input" | NodeError::MissingInput | Provide via config, connection, or inputs |
| "invalid input...expected...got" | NodeError::InvalidInput | Match Value variant to expected type |
| "cycle detected" | BuildError::CycleDetected | Add builder.enable_cycles(true) |
| "timed out after..." | RuntimeError::Timeout | Increase RuntimeConfig::timeout |
| "use of moved value" | Ownership (compile) | Don't use builder after .build() |
Before Building Workflow:
.build(®istry)? on WorkflowBuilder?? to propagate the BuildError?connect() calls use 4 parameters in correct order?enable_cycles(true) set?NodeRegistry?Before Executing Workflow:
execute().await? in async contexts (axum, tokio::main)?execute_sync() only in sync contexts (CLI, scripts)?RuntimeConfig::timeout set appropriately?? or match?// :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(®istry)?;
let result = runtime.execute(&workflow, ValueMap::new()).await?;
// :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?;
}
// :x: WRONG (swapped parameters)
builder.connect("node1", "node2", "result", "input");
// :white_check_mark: CORRECT (source, output, target, input)
builder.connect("node1", "result", "node2", "input");
// :x: WRONG (cycle without enable_cycles)
builder.connect("a", "out", "b", "in");
builder.connect("b", "out", "a", "in"); // Cycle!
let wf = builder.build(®istry)?; // 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(®istry)?; // OK
// :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)),
]));
BuildError? Fix workflow construction (nodes, connections, types)RuntimeError? Fix execution (inputs, timeouts, node logic)NodeError? Fix individual node configuration or inputsuse 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();
}
}
result.results.get("node_id") for output structurecrates/kailash-core/src/error.rscrates/kailash-core/src/workflow.rscrates/kailash-core/src/runtime.rscrates/kailash-nodes/src/.build(®istry)? on WorkflowBuilder before executionexecute_sync() inside async contexts (axum handlers, tokio::main)Result values with ? or explicit error matchingBuildError -- it means your workflow graph is invalid-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].
CI runs cargo test --workspace which includes doc-tests. Common failures:
CallerEvent::ToolCallDelta)Result but doc example doesn't use ? (e.g., WorkerAgent::new())SupervisorAgent::new() now 4 args)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>.
cargo check --workspace fails on magnus 0.8.2 — always --exclude kailash-ruby (#247)cargo +nightly fmt) — stable fmt produces different outputFor error troubleshooting, consult:
build-fix agent - Fix Rust compilation errors with minimal changesdataflow-specialist - DataFlow-specific patternsnexus-specialist - Nexus/axum integration debuggingtesting-specialist - Test debugging