Common issues

Match the symptom you see, then apply the fix. After config changes that affect the proxy, finish with capa install and often capa restart.

Symptom → fix

Symptom	Fix
Server won’t start / unhealthy	Run capa status. Check ~/.capa/logs/server.log. Then capa stop and capa start (or capa start -f to watch logs).
Skills missing in the client	Run capa clean then capa install. Confirm skill dirs (e.g. .cursor/skills/) and MCP config (e.g. .cursor/mcp.json). Reload the client.
Credentials not prompting	Use exact ${VarName} placeholders in the capabilities file. Ensure variables are referenced by servers/tools. Run capa install (web UI at the local server) or capa install -e. Try capa restart.
MCP / TLS: SELF_SIGNED_CERT_IN_CHAIN	For trusted internal servers only, set tlsSkipVerify: true on the server def and start the capa server with CAPA_ALLOW_TLS_SKIP_VERIFY=1 in its environment, then capa install and capa restart. See Credentials, auth, and TLS.
Installation blocked: forbidden phrase	A skill hit options.security.blockedPhrases. Remove the phrase from the skill, or adjust/remove blockedPhrases, then capa install again.
Tool not found	MCP tools in requires need @server_id.tool_id. Command tools use the plain id. Confirm capa status and that the tool id matches the MCP server.
Stale remote skills / plugins	capa install --no-cache, or capa cache clean then capa install.
capa wrap: binary missing	Install the provider CLI and ensure it is on PATH. Wrap fails fast before creating a workspace.
Provider / interactive prompt in CI	Non-TTY cannot prompt. Pass capa install -p <provider> (e.g. -p cursor) explicitly.
MCP not registered in client config	Expected when no tools or subagents are configured. Add at least one tool or subagent, then reinstall.
Token auth errors at MCP startup	Ensure Authorization (or equivalent) is in def.headers. Re-set ${VarName} via capa install -e or the web UI.

Rules and provider files

Symptom	Fix
Warning: Rule "<id>" is limited to …, but AGENTS.md is also read by …	Visibility conflict: another active provider reads the same instructions file. Adjust the rule’s providers, or set visibility: best-effort on the rule if that’s acceptable. See Rules → Conflicts.
Warning: appliesTo … can't be scoped natively for …	Scope conflict: the glob can’t become a nested instructions file. Use a directory glob (e.g. src/**) for an existing directory, or set scope: best-effort to accept a project-wide fold with an “Applies to” note.
Rule missing and the message says the rule was skipped	options.rules.conflicts is error (or onInstallError: stop is set), so conflicting rules are not installed. Resolve the conflict or opt in per rule with visibility / scope: best-effort.
Skipped <dir>/AGENTS.md: directory … does not exist	A directory appliesTo glob points at a folder that isn’t in the project. Create it or fix the glob, then capa install.
Gemini CLI ignores rules in AGENTS.md	With another AGENTS.md reader active, capa writes Gemini’s rules to GEMINI.md and sets .gemini/settings.json → context.fileName. Check that file, and remove a hand-added AGENTS.md entry if capa warned about it.
Antigravity shows duplicate skills	Since capa 2.2.0, capa installs Antigravity skills to .agents/skills/. Copies written by earlier releases to .agent/skills/ are not removed automatically: delete .agent/skills/ (or the capa-installed skill folders in it).

Credentials, auth, and TLS

Symptom	Fix
Install reports ⏳ N pending credentials (@server)	That server is missing a ${VarName} value, or a fromEnv / fromCommand / fromFile source failed. Provide the value (web UI or capa install -e) or fix the source, then capa install again. See Credentials.
Environment variable "NAME" is not set for a fromEnv source	The capa server resolves the source, so the variable must be in the environment the server started with. Set it, then run capa restart from that shell.
Failed to run secret command … / Command produced empty output	Run the fromCommand command yourself in the project directory. It must exit 0, print the secret to stdout, and finish within 10 seconds (for example, sign in to your secret manager CLI first).
Stored secrets stopped working after moving ~/.capa, switching user, or clearing the OS keyring	Secrets in capa.db are encrypted with a master key held in the OS keyring or ~/.capa/master.key. Without the original key they can’t be decrypted: re-enter variables (web UI or capa install -e), re-run capa auth, and reconnect OAuth servers. capa status shows which storage tier is in use.
capa auth or capa install hangs trying to open a browser in CI / a container	Add the global --headless flag so capa prints the URL instead. For git, prefer capa auth <host> --access-token <token>, which needs no browser.
capa auth git.corp.com fails with Unknown git provider	Browser OAuth only covers github.com and gitlab.com. Use capa auth git.corp.com --access-token <token> --type github-enterprise (or gitlab-self-managed).
Invalid Personal Access Token	The provider rejected the token. Check that it hasn’t expired and can read the repositories, then retry.
Warning: tlsSkipVerify requested but disabled	tlsSkipVerify: true is ignored unless the capa server runs with CAPA_ALLOW_TLS_SKIP_VERIFY=1. If CAPA_DISALLOW_TLS_SKIP_VERIFY=1 is set (for example by a managed-workstation policy), verification stays on regardless; give the MCP server a certificate that validates instead.
401 Unauthorized when calling http://127.0.0.1:5912/api/… from a script	The local API requires Authorization: Bearer <token> with the token from ~/.capa/auth.token (or CAPA_AUTH_TOKEN). Tokens in query strings are rejected. See Local API security.
421 Misdirected Request from the capa server	The request used a hostname other than localhost, 127.0.0.1, [::1], or the configured bind host. Open the UI and API through one of those.

Quick commands

capa status
capa stop
capa start -f

capa clean
capa install
capa install --no-cache
capa cache clean

capa wrap cursor          # after fixing PATH
capa install -p cursor    # CI-safe provider

Tip

Invalid -p values print the list of supported provider ids in the error message, useful when scripting CI.

See also

• Server lifecycle
• Credentials
• Lockfile and cache
• Getting help