error-troubleshooting
Kailash SDK的常见错误模式和故障排除指南,包括Nexus阻塞问题、连接参数错误、运行时执行错误、周期收敛问题、缺少.build()调用、参数验证错误和DataFlow模板语法错误。遇到错误、调试问题或询问"错误"、"故障排除"、"调试"、"不工作"、"挂起"、"超时"、"验证错误"、"连接错误"、"运行时错误"、"周期不收敛"、"缺少构建"或"模板语法"时使用。
📖 中文导读:Kailash SDK的常见错误模式和故障排除指南,包括Nexus阻塞问题、连接参数错误、运行时执行错误、周期收敛问题、缺少.build()调用、参数验证错误和DataFlow模板语法错误。遇到错误、调试问题或询问"错误"、"故障排除"、"调试"、"不工作"、"挂起"、"超时"、"验证错误"、"连接错误"、"运行时错误"、"周期不收敛"、"缺少构建"或"模板语法"时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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 ofruntime.execute(workflow.build()) - Solution: Always call
.build()before execution - Pattern:
runtime.execute(workflow.build())
- Symptom:
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
- Symptom:
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_completeflag
DataFlow Errors
DataFlow Template Syntax
- error-dataflow-template-syntax - Template string errors
- Symptom:
SyntaxErrorin template strings - Cause: Invalid template syntax in queries
- Solution: Use proper template format
- Pattern:
{{variable}}or{param}
- Symptom:
Quick Error Reference
Error by Symptom
| Symptom | Error Type | Quick Fix |
|---|---|---|
| API hangs forever | Nexus blocking | Use AsyncLocalRuntime |
| TypeError: expects Workflow | Missing .build() | Add .build() call |
| Node gets wrong data | Connection params | Check 4-parameter format |
| ValidationError | Parameter validation | Check required params |
| Infinite loop | Cycle convergence | Add convergence condition |
| Template SyntaxError | DataFlow template | Fix template syntax |
| Runtime fails | Runtime execution | Check logs, validate inputs |
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 documentationpattern-expert- Pattern validationgold-standards-validator- Check compliancetesting-specialist- Test debugging