Reference · Troubleshooting

Troubleshooting

The handful of things that trip people up first — what you see, why it happens, and the fix. Most are a launch flag, a reload, or a version away from working.

Channels don't seem live

You're seeing the channel MCP's instructions, but comments and approvals aren't reaching the agent live. The cause: Claude Code was launched without a channel flag. The MCP instructions load even without it, so seeing them does not prove the channel is live. Because Agentry's bridge is a custom, research-preview channel (not on the approved allowlist), relaunch it with the development flag — not --channels, which only loads allowlisted channels: 

claude --dangerously-load-development-channels plugin:agentry@agentry-dev
Gotcha The instructions loading is not proof the channel is live. Until you relaunch with the flag, everything falls back to the async file-watch loop. See Channels.

The Workbench won't open / the port is busy

The Workbench is a singleton on 127.0.0.1:4317. Running /agentry:workbench a second time focuses the already-running server — it never spawns a second one — so a "port busy" error usually means it's already up. Probe it: 

$ curl http://127.0.0.1:4317/healthz
Gotcha There is never a second Workbench process to kill. If /healthz answers, the server is up — re-running the command just brings its window to the front. See the Workbench page.

Plugin changes didn't take effect

You edited an agent, command, skill, or MCP server, but the change isn't live in the session. These changes are reload-gated: they only register on a reload/restart.

Gotcha Agent / command / skill / MCP changes register only on a session restart. Restart the session, then verify the change live.

Node version errors

Agentry requires Node ≥ 24. The memory MCP uses node:sqlite, which isn't available on older runtimes — so an older Node fails before anything useful happens.

Gotcha Check with node --version. If it's below 24, upgrade Node before launching.