agent-zero/skills/a0-debug-plugin/SKILL.md

name	description	version	tags	trigger_patterns
a0-debug-plugin	Diagnose Agent Zero plugin failures: loading, crashes, hooks, APIs, UI and settings.	1.0.0	plugins debug troubleshoot fix diagnose error broken	plugin not working plugin not loading plugin not showing plugin broken plugin error plugin missing plugin crash debug plugin troubleshoot plugin fix plugin

Agent Zero Plugin Debugger

Work through these checks in order. Stop at the first failure and fix it before continuing.

---

1. Plugin not appearing in the Plugins list

# Check plugin.yaml exists
ls /a0/usr/plugins/<name>/plugin.yaml

# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('/a0/usr/plugins/<name>/plugin.yaml'))"

# Check directory name doesn't start with '.'
ls /a0/usr/plugins/

Common causes:

• Missing plugin.yaml - plugin not discovered
• Invalid YAML syntax - plugin skipped silently
• Directory name starts with . - skipped by discovery

---

2. Plugin appears but won't enable

# Check toggle state
ls -la /a0/usr/plugins/<name>/.toggle-*

# Check for conflicting scoped toggles
ls -la project/.a0proj/plugins/<name>/.toggle-* 2>/dev/null
ls -la /a0/usr/agents/default/plugins/<name>/.toggle-* 2>/dev/null

---

3. API endpoint not responding

• Verify the handler file is in api/ and subclasses ApiHandler
• Route format: POST /api/plugins/<plugin_name>/<handler_filename_without_.py>
• Check for Python import errors on startup (check Agent Zero logs)
• Verify correct import paths: from agent import AgentContext not from helpers.context import AgentContext

# Check for syntax errors in handler
python3 -m py_compile /a0/usr/plugins/<name>/api/my_handler.py

---

4. Frontend component not rendering / store errors

• Check browser console for Alpine.js errors
• Verify the store file is imported in HTML <head> via <script type="module">
• Confirm Store Gate pattern is used (missing gate = undefined error if store not yet loaded)
• Verify store name in createStore(...) matches $store.<name> in templates

---

5. Extension point not injecting

• Check the HTML file is in extensions/webui/<correct_breakpoint_name>/
• Verify the breakpoint name exists in core UI (check webui/index.html or component files for <x-extension id="...">)
• Common breakpoints: sidebar-quick-actions-main-start, plugins-list-header-buttons, chat-input-bottom-actions-end
• Confirm the HTML file has a root element with x-data and an x-move-* directive

For backend extension hooks:

• Named lifecycle hooks must live under extensions/python/<point>/
• Implicit @extensible hooks must live under extensions/python/_functions/<module>/<qualname>/<start|end>/
• The retired flattened form extensions/python/<module>_<qualname>_<start|end>/ no longer loads

---

6. Settings not saving / loading wrong values

Config resolution order (highest priority first):

1. project/.a0proj/agents/<profile>/plugins/<name>/config.json
2. project/.a0proj/plugins/<name>/config.json
3. usr/agents/<profile>/plugins/<name>/config.json
4. usr/plugins/<name>/config.json
5. plugins/<name>/default_config.yaml

# Find which config file is actually being loaded
find /a0 -path "*/plugins/<name>/config.json" 2>/dev/null

---

7. hooks.py install hook not running

The install() hook is called automatically by the plugin installer after placement. If it didn't run:

• Check the function is named exactly install (not on_install or similar)
• Check for exceptions in the function (add try/except with print for debugging)
• Manually trigger in the framework runtime (not via code_execution_tool python - that uses /opt/venv, not /opt/venv-a0):

cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'install'))
print('Done')
"

If the pre_update() hook is not running before plugin updates:

• Check the function is named exactly pre_update
• Check for exceptions in the function
• Manually trigger it in the framework runtime the same way:

cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'pre_update'))
print('Done')
"

If the uninstall() hook is not running when the plugin is removed:

• Check the function is named exactly uninstall (not on_uninstall or similar)
• Check for exceptions in the function
• The uninstall() hook is called by uninstall_plugin() in helpers/plugins.py before the plugin directory is deleted. If the user removed the plugin manually (rm -rf), the hook was bypassed — always use the API or UI to uninstall.
• Manually trigger it in the framework runtime the same way:

cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'uninstall'))
print('Done')
"

---

8. Check Agent Zero logs

# Run from the Docker host; replace the name if needed
docker logs --tail 200 a0-instance

Plugin-related errors appear in the container output as Python tracebacks mentioning the plugin path.

---

How Plugin Discovery Works

1. Agent Zero walks usr/plugins/ then plugins/ at startup
2. Any directory containing plugin.yaml is treated as a plugin
3. usr/plugins/<name> takes priority over plugins/<name> when both exist (user overrides core)
4. Toggle state is evaluated: .toggle-0 disables, .toggle-1 enables, no file = enabled by default
5. Enabled plugins have their extensions/, api/, tools/, etc. registered into the runtime, including both named extension points and implicit _functions/... extensible hooks

Plugins are re-scanned when:

• Agent Zero restarts
• A plugin is installed/removed via the installer
• The "Refresh" action is triggered in the Plugins UI

---

References

• Plugin architecture: /a0/plugins/AGENTS.md
• Manage (install/update/uninstall): read /a0/skills/a0-manage-plugin/SKILL.md