error-troubleshooting
Skill0 starsChanged 7 months agoApache-2.0View on GitHub
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'.
- Reads credentials
In this repository37 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- .claude/guides/claude-code/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- core-sdkSkill
- dataflowSkill
- nexusSkill
- kaizenSkill
- kailash-mcpSkill
- cheatsheetsSkill
- development-guidesSkill
- nodes-referenceSkill
- workflow-patternsSkill
- deployment-gitSkill
- frontend-integrationSkill
- testing-strategiesSkill
- architecture-decisionsSkill
- code-templatesSkill
- enterprise-infrastructureSkill
- validation-patternsSkill
- gold-standardsSkill
- security-patternsSkill
- flutter-patternsSkill
- interactive-widgetsSkill
- enterprise-ai-uxSkill
- conversation-uxSkill
- uiux-design-principlesSkill
- value-auditSkill
- ai-interaction-patternsSkill
- eatp-referenceSkill
- coc-referenceSkill
- 29-pactSkill
- claude-code-patternsSkill
- kailash-mlSkill
- kailash-alignSkill
- co-referenceSkill
- managementSkill
- projectSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Check logs, validate inputs, test nodes individually, add LoggerNode for visibility
- Distinctive: line 68
All connections use 4 parameters?
- Distinctive: line 69
All required node parameters provided?
- Very specific: line 79
Always: check .build() was called
- Distinctive: line 81
Always: verify absolute imports when seeing import errors
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Kailash Error Troubleshooting
Common error patterns and solutions for Kailash SDK.
Sub-File Index
Critical Errors
- error-nexus-blocking - Nexus hangs or blocks
- Symptom: API hangs forever | Cause: LocalRuntime in Docker/async | Fix: Use AsyncLocalRuntime
- error-missing-build - Forgot
.build()- Symptom:
TypeError: execute() expects Workflow, got WorkflowBuilder| Fix:runtime.execute(workflow.build())
- Symptom:
Connection & Parameter Errors
- error-connection-exhaustion - Database connection exhaustion
- Symptom: "too many connections" | Fix: Use
external_poolparameter, setmax_pool_size = DB max / worker count
- Symptom: "too many connections" | Fix: Use
- error-connection-params - Invalid connections
- Symptom: Node gets wrong data | Fix: Use 4-param format
(source_id, source_param, target_id, target_param)
- Symptom: Node gets wrong data | Fix: Use 4-param format
- error-parameter-validation - Invalid node parameters
- Symptom:
ValidationError: Missing required parameter| Fix: Check node docs for required params
- Symptom:
Runtime & Cycle Errors
- error-runtime-execution - Runtime failures
- Check logs, validate inputs, test nodes individually, add LoggerNode for visibility
- error-cycle-convergence - Cycles don't converge
- Symptom: Infinite loop / max iterations exceeded | Fix: Add
cycle_completeconvergence check
- Symptom: Infinite loop / max iterations exceeded | Fix: Add
DataFlow Errors
- error-dataflow-template-syntax - Template string errors
- Symptom:
SyntaxErrorin template strings | Fix: Use{{variable}}syntax
- Symptom:
Kaizen Provider Errors
- error-kaizen-provider-config - Provider configuration issues
- Azure 400 "messages must contain 'json'" | Use
json_prompt_suffix()or setresponse_format - "Missing required parameter: response_format.type" | Don't put
api_versioninresponse_format - DeprecationWarning about
provider_config| Migrate toresponse_formatfield - Azure env var deprecation warnings | Switch to canonical names (
AZURE_ENDPOINT,AZURE_API_KEY)
- Azure 400 "messages must contain 'json'" | Use
Quick Error Reference
| 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 | Use {{variable}} syntax |
| Runtime fails | Runtime execution | Check logs, validate inputs |
| "too many connections" | Connection exhaustion | Use external_pool injection |
| Azure 400 "messages must contain 'json'" | Kaizen provider | Use json_prompt_suffix() or response_format |
| "Missing required parameter: response_format.type" | Kaizen provider | Don't put api_version in response_format |
DeprecationWarning about provider_config | Kaizen provider | Migrate to response_format field |
Error Prevention Checklist
- Called
.build()on WorkflowBuilder? - Using
AsyncLocalRuntimefor Docker/async? - All connections use 4 parameters?
- All required node parameters provided?
- Cyclic workflows have convergence checks?
- Template strings use
{{variable}}syntax? - Using
external_poolin multi-worker deployments? - Structured output in
response_format(notprovider_config)? - Azure using canonical env vars (
AZURE_ENDPOINT,AZURE_API_KEY)? structured_output_mode="explicit"for new agents?
Debugging Tips
- Always check
.build()was called - Never ignore connection validation errors
- Always verify absolute imports when seeing import errors
- Never assume mock tests found real issues -- use real infrastructure
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
pattern-expert- Pattern validationgold-standards-validator- Check compliancetesting-specialist- Test debugging
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

