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