Troubleshooting

Start with the smallest local signal:

caplets doctor

If you installed with npx, use:

npx caplets doctor

doctor should show the active Caplets paths and the checks Caplets can run for your configured integrations. Fix the first failed check, then rerun the same command.

Symptom map

Auth, Vault values, or remote clients disappeared after upgrading

Expected symptom: after upgrading from caplets@0.25.x or earlier to caplets@0.26.0 or later, previously configured credentials, Vault values or grants, remote clients, setup history, activity, or tracked global Caplets appear missing.

Do not recreate or overwrite the missing state. Caplets 0.26.0 and later use SQL as the authority and do not fall back to the legacy files. Stop every Caplets Host Node, then run the required one-time migration:

caplets storage migrate-legacy --dry-run
caplets storage migrate-legacy
caplets storage status --json

Resolve dry-run failures before the write migration and restart only after storage status reports ready. If a tracked Caplet is missing, restore the exact path named in the error or remove its stale lockfile entry, then rerun the dry run. See Authoritative Host State.

Agent cannot see Caplets

Expected symptom: the agent has no caplets__code_mode tool, or no Caplets MCP server is listed in the agent UI.

Run setup again, then restart the agent:

caplets setup
caplets doctor

Codex, Claude, OpenCode, and Pi usually read MCP or native plugin configuration at agent startup. If doctor is clean but the agent still cannot see Caplets, inspect the agent’s configured MCP servers and confirm daemon-first local setup wrote caplets attach <local-daemon-url>. caplets serve should appear only in manual fallback configs.

Agent	Verify registration
Codex	Run codex mcp list, then codex mcp get caplets; confirm caplets attach http://127.0.0.1:5387/ or your configured local daemon URL.
Claude	Run claude mcp list, then claude mcp get caplets; confirm the same daemon-backed attach command shape.
Other MCP clients	Inspect the client MCP JSON and confirm the caplets server command and args from Install.
OpenCode / Pi native	Confirm the native integration is using daemon defaults, explicit mode: "daemon", CAPLETS_MODE, or remote values and exposes caplets__code_mode.

Wrong config is loading

Expected symptom: doctor reports a different config than the file you edited, or a Caplet is missing after you add it.

Print the active user config path:

caplets config path

Override it for one command:

CAPLETS_CONFIG=/path/to/caplets.json caplets doctor

Project config should live at .caplets/config.json. User config is for personal agent setup; project config is for capabilities that should travel with a repository.

Serve defaults are not applying

Expected symptom: caplets serve --transport http or caplets daemon restart still uses a different host, port, auth mode, or public origin than the serve block you edited. Check the active user config path first:

caplets config path

The top-level serve block is respected only from user config. .caplets/config.json cannot control local HTTP serving and is ignored with a warning for security. Command flags and environment variables also win over user config, so remove --host, --port, CAPLETS_SERVER_URL, or related overrides before expecting defaults to apply.

CAPLETS_SERVER_URL must be a Current Host Origin such as https://host.example; non-root paths, queries, fragments, and embedded credentials are rejected. Route placement is not a serve default.

For daemon changes, run:

caplets daemon restart
caplets daemon status --json

The restart re-resolves user serve defaults for daemon fields that were not explicitly set at install time. If caplets setup still writes a loopback attach URL, that is intentional: local setup keeps the onboarding daemon credential-free and loopback-only even when your user defaults are broader.

Disable or inspect telemetry

Expected symptom: you want to disable anonymous telemetry, inspect local telemetry state, or see the sanitized events Caplets would send.

Disable telemetry for one process:

CAPLETS_DISABLE_TELEMETRY=1 caplets doctor

Disable telemetry in your user Caplets config:

caplets telemetry disable

Inspect state or run a local debug capture:

caplets telemetry status
caplets telemetry debug -- doctor

caplets telemetry rotate-id and caplets telemetry delete-id affect only the local anonymous ID. They do not delete provider-side historical anonymous events.

Copied install commands from Caplets sites may include a categorical marker such as CAPLETS_INSTALL_ATTRIBUTION=catalog_install. The marker is nonsecret, contains no browser identifier, and is consumed only as anonymous first-activation attribution. Remove the environment assignment before running the command if you do not want that attribution.

Code Mode returns ok: false

Expected symptom: a Code Mode call returns an error envelope instead of tool data.

First confirm the generated handles:

caplets code-mode types

Then rerun the smallest script that reproduces the failure and return the compact envelope:

const h = caplets.osv;
const ready = await h.check();
if (!ready.ok) return ready;
return await h.callTool("query_package_version", {
  ecosystem: "npm",
  name: "react",
  version: "18.2.0",
});

Use the returned error.code, error.message, and Caplet ID to repair the call. Do not paste a full raw downstream payload back to the agent unless the error depends on it.

Google auth asks for login again

Expected symptom: a Google Discovery Caplet worked before, but auth login or a tool call now reports missing scopes after you changed operation filters or the Discovery document.

Google Discovery Caplets infer OAuth scopes from the exposed operation set unless auth.scopes is configured. Re-run login for that Caplet so the stored token metadata matches the current scope set:

caplets auth login <caplet-id>
caplets doctor

If the Caplet should never ask for newly inferred scopes, configure auth.scopes explicitly and keep includeOperations narrow.

Vault-backed Caplet is quarantined

Expected symptom: doctor reports a Vault issue, or a Caplet that references $vault:... does not appear in the agent.

List the current Vault keys and grants:

caplets vault list
caplets vault access list

Then run the repair command from doctor. For a missing grant it will look like:

caplets vault access grant GH_TOKEN github

If the Caplet runs in a generic remote Current Host, target that runtime:

caplets vault access grant GH_TOKEN github --remote

Vault diagnostics never print raw values. Use Caplets Vault for the full setup and repair workflow.

Download returned an artifact

Expected symptom: a tool result has a top-level kind of local-artifact or remote-reference instead of inline bytes or text.

Binary downloads, Google media downloads, and oversized HTTP-like responses use Caplets media results. Local runtimes return local-artifact; read its path locally or pass its artifact URI back to another media-capable tool as media.artifact. Remote boundaries return remote-reference; use its uri because remote results do not expose filesystem path semantics. If you need a specific destination for a download, retry with filename or outputPath when the tool schema exposes those fields.

Remote attach fails

Expected symptom: remote mode starts, but attach cannot reach the runtime or authenticate.

Confirm the generic Current Host selection:

caplets remote login https://caplets.example.com
export CAPLETS_MODE=remote
export CAPLETS_REMOTE_URL=https://caplets.example.com
caplets doctor
caplets attach https://caplets.example.com --once

Current Host inputs contain only scheme, host, and optional port. A trailing root slash is normalized away; a non-root path, query, fragment, or embedded credential is rejected before network I/O. caplets attach --once validates the canonical Project Binding WebSocket URL once and exits.

If a reverse proxy is involved, it must expose /.well-known/caplets, /api, exact /mcp, and /dashboard at the origin root and forward WebSocket upgrades at /api/v1/attach/project-bindings/connect. Prefix-only hosting is unsupported.

If an old config uses caplets attach --transport http or attach HTTP bind flags, replace that server command with:

caplets serve --transport http --upstream-url https://caplets.example.com

Keep MCP client configs on caplets attach <url>.

Attach origin is wrong

Expected symptom: the agent connects to an unintended Current Host or rejects the URL before connecting.

Inspect the effective generic remote selection rather than copying tokens or endpoint internals into agent configuration:

caplets remote status
caplets doctor --json
caplets attach <current-host-origin> --once

Correct CAPLETS_MODE or the origin-only CAPLETS_REMOTE_URL, then restart the agent. Attach uses /api/v1/attach/*; ordinary Streamable HTTP MCP clients that bypass Attach use exact /mcp.

Project Binding smoke check fails

Expected symptom: a project Caplet exists, but the agent cannot use repository-local files or commands.

Check the project config location:

pwd
ls .caplets/config.json
caplets doctor

Run the agent from the project root. Managed Project Binding is available to native generic Current Host and loopback daemon sessions that provide project context when the host advertises support. Ordinary caplets attach <origin> is a thin MCP Adapter; use caplets attach <origin> --once only to validate manifest policy and the canonical WebSocket endpoint. If the capability needs setup commands, run those listed in its setup metadata before asking the agent to call it.

See Project Binding for exclusion rules, size limits, leases, and node-loss recovery.

OSV no-auth smoke test

If you need a public capability to separate Caplets setup from credential problems, install OSV:

caplets install spiritledsoftware/caplets osv

Then ask your agent to query OSV from Code Mode. If OSV works but another Caplet fails, the remaining issue is likely that Caplet’s auth, runtime, or downstream schema.