Guides
Troubleshooting#
How to read doctor output, why some hosts report hooks as unavailable, what the "requires sync, skipped" usage rows mean, the common ConnectorConfigError messages, and why telemetry can show nothing.
Reading doctor output#
agent-connector doctor loads each detected host adapter, runs its checks, and prints one status line per check. Any single [FAIL] makes the command exit 1; warnings alone never fail it.
| Status | Meaning |
|---|---|
[pass] | The check succeeded; nothing to do. |
[warn] | A non-fatal degradation (e.g. a capability the host can't honor). The command still exits 0 — warns alone never fail doctor. |
[FAIL] | A check that must be fixed. Any single FAIL makes the whole command exit non-zero (1). The fix: line shows the suggested remedy. |
A line reads [pass] <check> — <message>; a failing or warning check adds an indented fix: line with the suggested remedy. Run it scoped with doctor --targets <a,b> or against a specific config with --connector <path>; --json emits the per-platform results array.
"hooks unavailable here"#
The 10 mcp-only hosts (Warp, Cline, Trae, Zed, Codebuff, Mux, Pi, Windsurf, Junie, Mistral Vibe) have no hook layer — only the MCP server is installed. Detection and doctor surface "hooks unavailable here" for them; this is expected, not an error. Declared hooks are simply skipped (with a warning) on those targets. See the three paradigms.
The warn action → exit 1#
install and upgrade exit 1 when any change in the diff is a warn (glyph !) — for example a host that can't honor a requested transport (it downgrades-or-skips and reports it) or a surface an adapter doesn't support (it skips + warns). The write still succeeds; the non-zero exit is a signal to inspect the warnings, not a failure. This is distinct from doctor, where a [warn] does not change the exit code (only a [FAIL] does).
"requires sync, skipped" usage rows#
The host-usage layer reads each CLI's own logs read-only. Some hosts keep their usage data behind an external sync agent-connector does not perform, so agent-connector usage report prints those platforms as "requires sync, skipped" unless a local cache already exists:
cursorantigravityantigravity-clitraewarp
This is informational — it only means those rows are absent from the host-usage totals, not that anything is broken. Other hosts populate immediately.
Common ConnectorConfigError messages#
defineConnector validates eagerly and throws ConnectorConfigError on the first violation. The most common ones:
| Message | Cause & fix |
|---|---|
| id must be kebab-case matching /^[a-z0-9][a-z0-9-]*$/ or derivable from mcp/package metadata | The explicit id is invalid, or no id can be inferred from package.json, mcp metadata, or npx-style server args. |
| a connector must declare at least one of `server`, `hooks`, `commands`, `skills`, `subagents`, `memory`, `statusline`, `actions`, or a per-platform `nativeHooks` / `configPatch` declaration | No surface was declared. A connector needs at least one of those to do anything. |
| memory[<i>].content must not contain the literal marker token "agent-connector:begin" | Memory content containing the managed-block marker tokens (agent-connector:begin / agent-connector:end) would corrupt marker scanning. Rephrase the content; the 16 KiB hard cap throws a similar error. |
| server.command is required for stdio transport | transport: "stdio" was set without a string command. Add the executable to launch. |
| server.url is required for <transport> transport | A remote transport (http / sse / ws) was set without a string url. Add the endpoint. |
| skills[i].resources key must not escape the skill dir via ".." | A resource relpath was absolute, empty, `.`, or contained a `..` traversal (checked with both / and \ separators). Use a safe path inside the skill dir. |
Telemetry shows nothing#
If agent-connector telemetry report is empty, work through these in order:
| Reason | Fix |
|---|---|
| AGENT_CONNECTOR_TELEMETRY=0 (or telemetry: { enabled: false }) | Telemetry is disabled. Unset the env var / re-enable in config, then re-run. |
| The MCP server isn't wrapped | Only servers launched through agent-connector serve are measured (wrapForTelemetry, default on for stdio). Remote transports can't be intercepted. Re-sync so the entry is wrapped. |
| Nothing has been recorded yet | Rows appear after the wrapped server actually handles tools/call traffic. Exercise a tool first. |
| Host-native turns not calibrated / not opted in | model_turn rows only exist when host-native usage is enabled (hostNativeUsage / AGENT_CONNECTOR_HOST_NATIVE=1) on a supporting host. |
| The MCP isn't declared + wrapped by YOUR connector | Per-MCP / per-tool telemetry exists only for a server your own connector declares and serve-wraps — serve loads a registered connector and stamps every row with its id. An already-installed third-party MCP you didn't author produces no per-tool rows here; that is a capability boundary, not a bug. For an MCP you didn't author, the connector-free `usage` command shows per-CLI / per-model totals (not per-MCP). |