π Debugging Guide
Having trouble with SuperOptiX? This guide will help you diagnose and fix common issues, from installation to agent orchestration.
π¦ Common Errors & Fixes
- Installation issues:
- Python version mismatch
- Missing dependencies
-
Solution: Check
pyproject.toml
, use a clean virtual environment -
CLI errors:
- βcommand not foundβ, βnot a super projectβ
-
Solution: Run from project root, ensure
.super
file exists -
Agent compilation errors:
- YAML syntax errors, missing playbooks
-
Solution: Validate YAML, check agent directory
-
Model/server errors:
- Model not found, server not running
-
Solution: Check model install, server logs, port conflicts
-
Memory/tool integration errors:
- Backend not installed, misconfigured settings
- Solution: Check backend install, review config
π οΈ Debugging Tools & Techniques
- Use
super <command> --verbose
for more output - Check logs in
logs/
or as printed in the terminal - Use Python debuggers (
pdb
, IDE breakpoints) - Enable tracing/observability (if available)
π Troubleshooting Checklist
- Are you in the project root? (
.super
file present) - Did you activate your virtual environment?
- Are all dependencies installed?
- Is your YAML valid? (use YAML Linter)
- Is the model installed and server running?
- Are you using the correct CLI command?
β FAQ
-
βWhy do I get βcommand not foundβ?β
Make sure you installed SuperOptiX and activated your environment. -
βWhy does my agent not appear?β
Check the agent directory and playbook naming. -
βWhy do I get a backend error?β
Ensure the required backend (memory, tool, model) is installed and configured.
π Additional Resources
If you find a bug, please report it with your OS, Python version, CLI command, and error output!