---

name: error-troubleshooting description: "Common error patterns and troubleshooting guides for Kailash SDK including Nexus blocking issues, connection parameter errors, runtime execution errors, cycle convergence problems, missing .build() calls, parameter validation errors, and DataFlow template syntax errors. Use when encountering errors, debugging issues, or asking about 'error', 'troubleshooting', 'debugging', 'not working', 'hangs', 'timeout', 'validation error', 'connection error', 'runtime error', 'cycle not converging', 'missing build', or 'template syntax'."

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

Copy# ❌ 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

Copy# ❌ 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

Copy# ❌ 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

Copy# ❌ 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

Copy# ❌ 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