| 1 | --- |
| 2 | name: a0-debug-plugin |
| 3 | description: Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving unexpectedly. |
| 4 | version: 1.0.0 |
| 5 | tags: ["plugins", "debug", "troubleshoot", "fix", "diagnose", "error", "broken"] |
| 6 | trigger_patterns: |
| 7 | - "plugin not working" |
| 8 | - "plugin not loading" |
| 9 | - "plugin not showing" |
| 10 | - "plugin broken" |
| 11 | - "plugin error" |
| 12 | - "plugin missing" |
| 13 | - "plugin crash" |
| 14 | - "debug plugin" |
| 15 | - "troubleshoot plugin" |
| 16 | - "fix plugin" |
| 17 | --- |
| 18 | |
| 19 | # Agent Zero Plugin Debugger |
| 20 | |
| 21 | Work through these checks in order. Stop at the first failure and fix it before continuing. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## 1. Plugin not appearing in the Plugins list |
| 26 | |
| 27 | ```bash |
| 28 | # Check plugin.yaml exists |
| 29 | ls /a0/usr/plugins/<name>/plugin.yaml |
| 30 | |
| 31 | # Validate YAML |
| 32 | python3 -c "import yaml; yaml.safe_load(open('/a0/usr/plugins/<name>/plugin.yaml'))" |
| 33 | |
| 34 | # Check directory name doesn't start with '.' |
| 35 | ls /a0/usr/plugins/ |
| 36 | ``` |
| 37 | |
| 38 | Common causes: |
| 39 | - Missing `plugin.yaml` - plugin not discovered |
| 40 | - Invalid YAML syntax - plugin skipped silently |
| 41 | - Directory name starts with `.` - skipped by discovery |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## 2. Plugin appears but won't enable |
| 46 | |
| 47 | ```bash |
| 48 | # Check toggle state |
| 49 | ls -la /a0/usr/plugins/<name>/.toggle-* |
| 50 | |
| 51 | # Check for conflicting scoped toggles |
| 52 | ls -la project/.a0proj/plugins/<name>/.toggle-* 2>/dev/null |
| 53 | ls -la /a0/usr/agents/default/plugins/<name>/.toggle-* 2>/dev/null |
| 54 | ``` |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## 3. API endpoint not responding |
| 59 | |
| 60 | - Verify the handler file is in `api/` and subclasses `ApiHandler` |
| 61 | - Route format: `POST /api/plugins/<plugin_name>/<handler_filename_without_.py>` |
| 62 | - Check for Python import errors on startup (check Agent Zero logs) |
| 63 | - Verify correct import paths: `from agent import AgentContext` not `from helpers.context import AgentContext` |
| 64 | |
| 65 | ```bash |
| 66 | # Check for syntax errors in handler |
| 67 | python3 -m py_compile /a0/usr/plugins/<name>/api/my_handler.py |
| 68 | ``` |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## 4. Frontend component not rendering / store errors |
| 73 | |
| 74 | - Check browser console for Alpine.js errors |
| 75 | - Verify the store file is imported in HTML `<head>` via `<script type="module">` |
| 76 | - Confirm Store Gate pattern is used (missing gate = undefined error if store not yet loaded) |
| 77 | - Verify store name in `createStore(...)` matches `$store.<name>` in templates |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | ## 5. Extension point not injecting |
| 82 | |
| 83 | - Check the HTML file is in `extensions/webui/<correct_breakpoint_name>/` |
| 84 | - Verify the breakpoint name exists in core UI (check `webui/index.html` or component files for `<x-extension id="...">`) |
| 85 | - Common breakpoints: `sidebar-quick-actions-main-start`, `plugins-list-header-buttons`, `chat-input-bottom-actions-end` |
| 86 | - Confirm the HTML file has a root element with `x-data` and an `x-move-*` directive |
| 87 | |
| 88 | For backend extension hooks: |
| 89 | - Named lifecycle hooks must live under `extensions/python/<point>/` |
| 90 | - Implicit `@extensible` hooks must live under `extensions/python/_functions/<module>/<qualname>/<start|end>/` |
| 91 | - The retired flattened form `extensions/python/<module>_<qualname>_<start|end>/` no longer loads |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## 6. Settings not saving / loading wrong values |
| 96 | |
| 97 | Config resolution order (highest priority first): |
| 98 | 1. `project/.a0proj/agents/<profile>/plugins/<name>/config.json` |
| 99 | 2. `project/.a0proj/plugins/<name>/config.json` |
| 100 | 3. `usr/agents/<profile>/plugins/<name>/config.json` |
| 101 | 4. `usr/plugins/<name>/config.json` |
| 102 | 5. `plugins/<name>/default_config.yaml` |
| 103 | |
| 104 | ```bash |
| 105 | # Find which config file is actually being loaded |
| 106 | find /a0 -path "*/plugins/<name>/config.json" 2>/dev/null |
| 107 | ``` |
| 108 | |
| 109 | --- |
| 110 | |
| 111 | ## 7. hooks.py install hook not running |
| 112 | |
| 113 | The `install()` hook is called automatically by the plugin installer after placement. If it didn't run: |
| 114 | - Check the function is named exactly `install` (not `on_install` or similar) |
| 115 | - Check for exceptions in the function (add try/except with print for debugging) |
| 116 | - Manually trigger in the **framework runtime** (not via `code_execution_tool` python - that uses `/opt/venv`, not `/opt/venv-a0`): |
| 117 | |
| 118 | ```bash |
| 119 | cd /a0 && /opt/venv-a0/bin/python -c " |
| 120 | import asyncio |
| 121 | from helpers.plugins import call_plugin_hook |
| 122 | asyncio.run(call_plugin_hook('<plugin_name>', 'install')) |
| 123 | print('Done') |
| 124 | " |
| 125 | ``` |
| 126 | |
| 127 | If the `pre_update()` hook is not running before plugin updates: |
| 128 | - Check the function is named exactly `pre_update` |
| 129 | - Check for exceptions in the function |
| 130 | - Manually trigger it in the **framework runtime** the same way: |
| 131 | |
| 132 | ```bash |
| 133 | cd /a0 && /opt/venv-a0/bin/python -c " |
| 134 | import asyncio |
| 135 | from helpers.plugins import call_plugin_hook |
| 136 | asyncio.run(call_plugin_hook('<plugin_name>', 'pre_update')) |
| 137 | print('Done') |
| 138 | " |
| 139 | ``` |
| 140 | |
| 141 | If the `uninstall()` hook is not running when the plugin is removed: |
| 142 | - Check the function is named exactly `uninstall` (not `on_uninstall` or similar) |
| 143 | - Check for exceptions in the function |
| 144 | - 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. |
| 145 | - Manually trigger it in the **framework runtime** the same way: |
| 146 | |
| 147 | ```bash |
| 148 | cd /a0 && /opt/venv-a0/bin/python -c " |
| 149 | import asyncio |
| 150 | from helpers.plugins import call_plugin_hook |
| 151 | asyncio.run(call_plugin_hook('<plugin_name>', 'uninstall')) |
| 152 | print('Done') |
| 153 | " |
| 154 | ``` |
| 155 | |
| 156 | --- |
| 157 | |
| 158 | ## 8. Check Agent Zero logs |
| 159 | |
| 160 | ```bash |
| 161 | # Run from the Docker host; replace the name if needed |
| 162 | docker logs --tail 200 a0-instance |
| 163 | ``` |
| 164 | |
| 165 | Plugin-related errors appear in the container output as Python tracebacks mentioning the plugin path. |
| 166 | |
| 167 | --- |
| 168 | |
| 169 | ## How Plugin Discovery Works |
| 170 | |
| 171 | 1. Agent Zero walks `usr/plugins/` then `plugins/` at startup |
| 172 | 2. Any directory containing `plugin.yaml` is treated as a plugin |
| 173 | 3. `usr/plugins/<name>` takes priority over `plugins/<name>` when both exist (user overrides core) |
| 174 | 4. Toggle state is evaluated: `.toggle-0` disables, `.toggle-1` enables, no file = enabled by default |
| 175 | 5. Enabled plugins have their `extensions/`, `api/`, `tools/`, etc. registered into the runtime, including both named extension points and implicit `_functions/...` extensible hooks |
| 176 | |
| 177 | Plugins are re-scanned when: |
| 178 | - Agent Zero restarts |
| 179 | - A plugin is installed/removed via the installer |
| 180 | - The "Refresh" action is triggered in the Plugins UI |
| 181 | |
| 182 | --- |
| 183 | |
| 184 | ## References |
| 185 | |
| 186 | - Plugin architecture: `/a0/plugins/AGENTS.md` |
| 187 | - Manage (install/update/uninstall): read `/a0/skills/a0-manage-plugin/SKILL.md` |