A0 Debug 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//plugin.yaml

# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('/a0/usr/plugins//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//.toggle-*

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

---

3. API endpoint not responding

• Verify the handler file is in api/ and subclasses ApiHandler
• Route format: POST /api/plugins//
• 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//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 ` via `
• Confirm Store Gate pattern is used (missing gate = undefined error if store not yet loaded)
• Verify store name in createStore(...) matches $store. in templates

---

5. Extension point not injecting

• Check the HTML file is in extensions/webui//
• Verify the breakpoint name exists in core UI (check webui/index.html or component files for ``)
• 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//
• Implicit @extensible hooks must live under extensions/python/_functions////
• The retired flattened form extensions/python/__/ no longer loads

---

6. Settings not saving / loading wrong values

Config resolution order (highest priority first):

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

# Find which config file is actually being loaded
find /a0 -path "*/plugins//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('', '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('', 'pre_update'))
print('Done')
"

---

8. Check Agent Zero logs

# Find recent log files
ls -lt /a0/logs/*.html | head -5

Plugin-related errors appear 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/ takes priority over plugins/ 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/docs/agents/AGENTS.plugins.md
• Manage (install/update/uninstall): read /a0/skills/a0-manage-plugin/SKILL.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Gen-Verse
• Source: Gen-Verse/PAST-Bench
• License: Apache-2.0
• Homepage: https://arxiv.org/abs/2608.04003

Install and usage instructions live in the source repository linked above.