Kailash Error Troubleshooting

Missing .build() Call

• error-missing-build - Forgot to call .build()
  • Symptom: TypeError: execute() expects Workflow, got WorkflowBuilder
  • Cause: runtime.execute(workflow) instead of runtime.execute(workflow.build())
  • Solution: Always call .build() before execution
  • Pattern: runtime.execute(workflow.build())

Connection & Parameter Errors

Connection Parameter Errors

• error-connection-params - Invalid connections
  • Symptom: Node doesn't receive expected data
  • Cause: Wrong 4-parameter connection format
  • Solution: Use (source_id, source_param, target_id, target_param)
  • Common mistake: Wrong parameter names

Parameter Validation Errors

• error-parameter-validation - Invalid node parameters
  • Symptom: ValidationError: Missing required parameter
  • Cause: Missing or incorrect node parameters
  • Solution: Check node documentation for required params
  • Tool: Use validate-parameters skill

Runtime Errors

Runtime Execution Errors

• error-runtime-execution - Runtime failures
  • Symptom: Workflow fails during execution
  • Cause: Various runtime issues
  • Solutions: Check logs, validate inputs, test nodes individually
  • Debug: Use LoggerNode for visibility

Cyclic Workflow Errors

Cycle Convergence Errors

• error-cycle-convergence - Cycles don't converge
  • Symptom: Workflow runs forever, max iterations exceeded
  • Cause: No convergence condition or bad logic
  • Solution: Add proper convergence check
  • Pattern: Use cycle_complete flag

DataFlow Errors

DataFlow Template Syntax

• error-dataflow-template-syntax - Template string errors
  • Symptom: SyntaxError in template strings
  • Cause: Invalid template syntax in queries
  • Solution: Use proper template format
  • Pattern: {{variable}} or {param}

Quick Error Reference

Error by Symptom

Error Prevention Checklist

Before Running Workflow:

• Called .build() on WorkflowBuilder?
• Using AsyncLocalRuntime for Docker/FastAPI?
• All connections use 4 parameters?
• All required node parameters provided?
• Cyclic workflows have convergence checks?
• Template strings use correct syntax?

Common Error Patterns

1. Nexus Blocking/Hanging

# ❌ WRONG (causes hang in Docker)
from kailash.runtime import LocalRuntime
nexus = Nexus(workflows, runtime_factory=lambda: LocalRuntime())

# ✅ CORRECT (async-first, no threads)
from kailash.runtime import AsyncLocalRuntime
nexus = Nexus(workflows, runtime_factory=lambda: AsyncLocalRuntime())

2. Missing .build() Call

# ❌ WRONG
workflow = WorkflowBuilder()
workflow.add_node(...)
results = runtime.execute(workflow)  # TypeError!

# ✅ CORRECT
workflow = WorkflowBuilder()
workflow.add_node(...)
results = runtime.execute(workflow.build())  # Always .build()

3. Connection Parameter Errors

# ❌ WRONG (only 2 parameters)
workflow.add_connection("node1", "node2")

# ❌ WRONG (wrong parameter names)
workflow.add_connection("node1", "output", "node2", "input_data")
# but node2 expects "data" not "input_data"

# ✅ CORRECT (4 parameters, correct names)
workflow.add_connection("node1", "result", "node2", "data")

4. Cycle Convergence Issues

# ❌ WRONG (infinite loop)
workflow.add_node("CycleNode", "cycle", {
    "max_iterations": 1000  # Will run all 1000
})

# ✅ CORRECT (with convergence)
workflow.add_node("PythonCodeNode", "check", {
    "code": """
if abs(current - previous) < 0.01:
    cycle_complete = True