Kailash Error Troubleshooting

Comprehensive troubleshooting guides for common Kailash SDK errors and issues.

Overview

Common error patterns and solutions for:

• •Nexus blocking and timeout issues
• •Connection parameter errors
• •Runtime execution problems
• •Cycle convergence failures
• •Missing .build() calls
• •Parameter validation errors
• •DataFlow template syntax errors

Reference Documentation

Critical Errors

Nexus Blocking (MOST COMMON)

• •error-nexus-blocking - Nexus hangs or blocks
  • •Symptom: Nexus API hangs forever, no response
  • •Cause: Using LocalRuntime in Docker/FastAPI
  • •Solution: Use AsyncLocalRuntime
  • •Prevention: Always use async runtime in containers

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
else:
    cycle_complete = False
"""
})

5. DataFlow Template Errors

# ❌ WRONG
query = "SELECT * FROM users WHERE id = {user_id}"  # Invalid

# ✅ CORRECT
query = "SELECT * FROM users WHERE id = {{user_id}}"  # DataFlow template

Debugging Strategies

Step 1: Check Error Message

• •Read full error message and stack trace
• •Identify error type and location
• •Check if it matches known patterns

Step 2: Validate Configuration

• •Runtime: AsyncLocalRuntime for Docker?
• •Build: Called .build()?
• •Connections: 4 parameters?
• •Parameters: All required params?

Step 3: Test Components

• •Test nodes individually
• •Test with minimal workflow
• •Add LoggerNode for visibility
• •Check intermediate results

Step 4: Check Documentation

• •Node documentation for parameters
• •Framework-specific guides
• •Error troubleshooting guides
• •Gold standards for best practices

When to Use This Skill

Use this skill when you encounter:

• •API hanging or blocking
• •Runtime errors during execution
• •Validation errors
• •Connection issues
• •Cyclic workflow problems
• •DataFlow errors
• •Any error message or unexpected behavior

Related Skills

• •16-validation-patterns - Validation patterns
• •17-gold-standards - Best practices to avoid errors
• •01-core-sdk - Core patterns
• •02-dataflow - DataFlow specifics
• •03-nexus - Nexus specifics

Support

For error troubleshooting, invoke:

• •sdk-navigator - Find relevant documentation
• •pattern-expert - Pattern validation
• •gold-standards-validator - Check compliance
• •testing-specialist - Test debugging