plugin disabled — every hook exits immediately | No parseable config, OPENVIKING_MEMORY_ENABLED=0, or claude_code.enabled: false in ov.conf | Fix the reason it names. Fresh machine: create ~/.openviking/ovcli.conf with url + api_key (chmod 600). |
ovcli.conf cannot be parsed | Trailing comma/comment; the plugin treats the file as absent | Fix the JSON. This is the most common "installed but nothing happens". |
not registered in installed_plugins.json / claude plugin list does not show … | Plugin never installed, or installed under an old id | Re-run the one-line installer (bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness claude; add --dist tos where GitHub is blocked). |
plugin is disabled in ~/.claude/settings.json | Installed but enabledPlugins is false/missing | claude plugin enable openviking-memory@openviking, restart Claude Code. |
marketplace 'openviking' … missing directory / registered as a file | The checkout/archive moved, or a file-type marketplace (fails marketplace update with EISDIR) | claude plugin marketplace remove openviking then re-run the installer. |
no skills/ directory in this plugin copy / registered version behind the repo | Stale version-keyed cache; claude plugin update is a no-op when the version string did not change | claude plugin marketplace update openviking && claude plugin uninstall openviking-memory@openviking && claude plugin install openviking-memory@openviking. |
legacy openviking hooks … settings.json / extra plugin ids / user-scope MCP openviking | Pre-2.0 install residue; every hook fires twice, MCP server registered twice | Remove the openviking entries from .hooks in ~/.claude/settings.json (back it up), claude plugin uninstall <stale id>, claude mcp remove openviking -s user. |
node is not on PATH / node < 18 | Hooks and .mcp.json run the bare command node; GUI/IDE launches often lack nvm/volta shims | Put node on PATH for the launching environment, or set PATH in the env block of ~/.claude/settings.json. |
server unreachable (refused / dns / timeout / tls) | Wrong url/port, server down, DNS/VPN, private CA | Compare with curl -sS <url>/health. curl OK + doctor fails ⇒ proxy or CA issue (see Step 3). |
base URL ends with /api/v1 or /mcp, no scheme, GET /health → 404 | url shape wrong (paths are concatenated bare); Cloud needs the /openviking prefix | Fix url to the API root. |
api key rejected (200 from /health with no identity) then system/status → 401 Invalid API Key | Key invalid/revoked/for another deployment. A 3-segment key for a non-existent account looks identical. | Get the key re-issued; check no env var shadows ovcli.conf ("← env" in the Configuration section). |
using the ROOT api key / 403 ROOT API keys cannot access tenant-scoped data APIs | api_key fell through to ov.conf server.root_api_key, or the user pasted the root key | Create a user key (POST /api/v1/admin/accounts/<account>/users with the root key) and put it in ovcli.conf. |
server is in trusted mode and needs account + user / 400 Trusted mode requests must include… | Server identity comes from headers | Set account and user in ovcli.conf. |
configured account/user differ from the key's identity | In api_key mode the server ignores X-OpenViking-Account/User; data lands under the key's identity | Remove them or use a key for that identity. Explains "I changed the account but nothing changed". |
POST /mcp tools/list → 404/406/502/504 while /health is fine | Reverse proxy not forwarding /mcp, rewriting Accept, or buffering SSE | Fix the proxy (proxy_buffering off, forward /mcp, pass Authorization). |
proxy variables set + curl works but doctor/hook fails | Node's fetch ignores HTTP(S)_PROXY; the plugin ships no proxy/CA handling | NODE_USE_ENV_PROXY=1 or NODE_EXTRA_CA_CERTS=<ca.pem> in the environment that launches Claude Code (env block of ~/.claude/settings.json). |
last auto-recall … reason=offline/bypass/disabled/short_query | The hook ran and chose not to inject | offline → connection; bypass → OPENVIKING_BYPASS_SESSION*; short_query → prompt shorter than minQueryLength; only no_results/filtered_out mean the search actually ran. Note that a 401 on the search call also reads as no_results. |
turns_failed > 0 / capture payload(s) waiting | Writes rejected (401/403/404 are dropped, not queued) or server was down (queued, replayed at next SessionStart) | Fix credentials/connection; OPENVIKING_WRITE_PATH_ASYNC=0 makes the error visible on stderr. |
MCP proxy last started against <other url> | The proxy is a long-lived process; a changed url only takes effect after restart | Restart Claude Code or /mcp → reconnect. Key rotation self-heals after a 401 if ovcli.conf changed on disk. |
recall is pinned to the legacy /search/recall endpoint | One 4xx mentioning "mode" pins recall for 6h | rm ~/.openviking/state/context-face.json. |
no hook log … debug is on but no hook has run | Hooks are not being spawned at all | Registration/enablement/node problem, not a server problem. |
ov.conf has a top-level 'claude_code' block / 'codex' block / server.url is rejected | Plugin-only keys in the server's own config; the server refuses to start at its next restart (Unknown config field / Extra inputs are not permitted) | Move them to ovcli.conf (plugin.<harness>, url) and delete them from ov.conf. Ignore only if this ov.conf never starts a server. |
nothing listens on port … — the server is not running | Server down or never started; a stale .openviking.pid means it died | Start it (openviking-server; first time openviking-server init) in a terminal and read the startup output. Ask before restarting a server the user runs. |
/ready: embedding → error … | The running server cannot call its embedding provider: recall searches nothing, commits extract nothing | Fix embedding.* (api_key/api_base/model) in ov.conf and restart; openviking-server doctor prints the provider's reply. |
/ready: vectordb → … / /ready: agfs → … | Storage broken: disk full, two servers on one workspace, corrupted index | Server log; stop the duplicate; free disk. |
server is still initializing (503 /ready) | First start downloads a local embedding model, or init is slow | Wait and rerun; if it never finishes, the server log. |
docker container is up but has no ov.conf | Official image started without a config mount (every request 503s) | Mount ~/.openviking at /app/.openviking, or docker exec -it openviking openviking-server init. |
