Troubleshooting

Troubleshooting

Symptom-to-fix reference for threadnote. Each section gives the symptom and the fix commands. Logs for the local server live at ~/.openviking/logs/server.log; the default bind address is 127.0.0.1:1933. See Installation and Configuration for setup details.

openviking-server Missing

Symptom: the openviking-server binary is not found.

threadnote install

The installer prefers uv, then pipx, then python3 -m pip install --user.

uv Fails With UnknownIssuer

Symptom: uv reports invalid peer certificate: UnknownIssuer. Some corporate machines trust PyPI through certificates installed in the system keychain.

Threadnote already passes --native-tls when it uses uv so those system certificates are loaded. If an older install still fails, retry with the env flag, or switch to a different Python installer:

UV_NATIVE_TLS=1 threadnote install
threadnote install --package-manager pipx
threadnote install --package-manager pip

Model Download Fails With CERTIFICATE_VERIFY_FAILED

Symptom: ~/.openviking/logs/server.log shows SSLCertVerificationError, self-signed certificate in certificate chain, or Failed to download local embedding model while OpenViking fetches the embedding model from Hugging Face.

threadnote repair --package-manager uv
threadnote doctor --dry-run

Threadnote installs pip-system-certs into the OpenViking environment so Python requests can use OS-trusted certificates. If an older release tries to reinstall all of OpenViking and fails while fetching packages such as openai, install the certificate bridge directly into the existing environment:

uv pip install --native-tls --python "$(dirname "$(realpath "$(which openviking-server)")")/python" pip-system-certs
threadnote start

Local Embedding Extra Missing

Symptom: the server log says llama-cpp-python is missing. The default OpenViking config uses the local embedding backend.

threadnote install

The installer repairs this by installing openviking[local-embed].

Server Health Fails

Symptom: doctor reports WARN openviking health: connect ECONNREFUSED 127.0.0.1:1933 — the local server is not running.

threadnote start
threadnote doctor --dry-run

Check whether the server is up directly:

curl http://127.0.0.1:1933/health

For detached starts, logs are written to:

~/.openviking/logs/server.log

If start reports that OpenViking did not become healthy, open that log. Certificate failures during the first embedding model download are covered above.

Port Already In Use

Symptom: another process already owns port 1933. Projects serving localhost:80, localhost:443, or custom /etc/hosts hostnames do not conflict — those are different host and port bindings.

Pick a different port and keep it consistent across start and the agent MCP config:

THREADNOTE_PORT=1934 threadnote start
THREADNOTE_PORT=1934 threadnote mcp-install codex --apply

Seed Skips Files

Symptom: seed skips one or more files. Skipped files usually matched the secret detector after redaction.

Inspect the file manually and either remove the risky content or leave it out of the manifest. See Safety and Security for the redaction and scanning rules.

seed-skills --native Fails With [INTERNAL]

Symptom: native skill ingestion fails and the server log shows an OpenAI quota, rate-limit, or authentication error. Native mode generates skill overviews with the configured VLM provider.

Run seed-skills without --native. The default mode stores SKILL.md files as searchable resources and does not require native overview generation.

After changing ~/.openviking/ov.conf, restart the server:

threadnote stop
threadnote start

Claude MCP Fails While Health Is OK

Symptom: the server is healthy at /health, but an agent configured against the raw HTTP MCP endpoint fails or returns 404.

The default Threadnote setup does not require the raw OpenViking HTTP MCP route. Use the bundled stdio adapter instead:

threadnote mcp-install claude --apply
claude mcp list

mcp-install claude writes user-scoped Claude config by default. This is intentional: local-scoped config only applies to one repo/project, and the threadnote shim runs the implementation from the checkout that installed it. Only use --native-http with an OpenViking build that actually exposes /mcp.

Worktree Was Deleted

Symptom: a branch or worktree was deleted and the launcher config still points at scripts inside it.

Memories live in ~/.openviking/data, so deleting a branch or worktree does not delete stored memories. From any fresh checkout, run:

threadnote repair

repair reinstalls the threadnote shim, repairs generated config files, starts OpenViking if needed, and rewrites Codex/Claude/Cursor/Copilot MCP configs to point at the current checkout.

MCP Install Is Only Printing Commands

Symptom: mcp-install prints commands instead of applying them. This is expected — it dry-runs by default.

Run with --apply after reviewing the command:

threadnote mcp-install codex --apply
threadnote mcp-install cursor --apply
threadnote mcp-install copilot --apply

mcp-install cursor updates the global ~/.cursor/mcp.json; restart Cursor or open a fresh agent session afterward. mcp-install copilot updates the VS Code user-profile mcp.json; restart VS Code or run MCP: List Servers from the Command Palette. If VS Code uses a custom profile path, set THREADNOTE_COPILOT_MCP_CONFIG to that mcp.json path before running the command.

Cursor MCP Tool Says Query Is Missing

Symptom: Cursor shows an error like expected string, received undefined for the Threadnote search tool — the MCP server started but Cursor called the tool without JSON arguments.

Prefer the Threadnote-named tool and pass a query explicitly:

{"query": "current repo latest handoff"}

Current adapters expose recall_context for this flow. Older adapters expose search; both require the same query argument. Run threadnote repair after upgrading if Cursor still lists only stale tools.

Uninstall Without Losing Memories

Symptom: you want to remove Threadnote but keep stored memories.

threadnote uninstall --dry-run
threadnote uninstall

By default, uninstall removes Threadnote-managed shims, MCP config, launchd config, and managed user instruction blocks while preserving THREADNOTE_HOME. To delete local OpenViking data too, pass --erase-memories.

See also: Installation, Configuration, CLI Reference.