Skip to content

troubleshooting.md

Latest commit

 

History

History
201 lines (134 loc) · 6.17 KB

troubleshooting.md

File metadata and controls

201 lines (134 loc) · 6.17 KB

Troubleshooting

openviking-server Missing

Run:

threadnote install

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

uv Fails With UnknownIssuer

Some corporate machines trust PyPI through certificates installed in the system keychain. Threadnote passes --native-tls when it uses uv so those system certificates are loaded.

If an older install still fails with invalid peer certificate: UnknownIssuer, retry with:

UV_NATIVE_TLS=1 threadnote install

Or use a different Python installer:

threadnote install --package-manager pipx
threadnote install --package-manager pip

Model Download Fails With CERTIFICATE_VERIFY_FAILED

On install or first start, OpenViking may download the local embedding model from Hugging Face. If ~/.openviking/logs/server.log shows SSLCertVerificationError, self-signed certificate in certificate chain, or Failed to download local embedding model, repair the OpenViking Python environment and start again:

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

Threadnote installs pip-system-certs into the OpenViking environment so Python requests can use certificates trusted by the operating system.

If an older Threadnote release tries to reinstall all of OpenViking and fails while fetching packages such as openai, install the certificate bridge directly into the existing OpenViking environment:

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

Local Embedding Extra Missing

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

threadnote install

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

Server Health Fails

Current Threadnote installs start the local server by default. If doctor reports WARN openviking health: connect ECONNREFUSED 127.0.0.1:1933, the local server is not running. Start it and recheck:

threadnote start
threadnote doctor --dry-run

Check whether the server is running:

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

The default bind address is 127.0.0.1:1933. This does not conflict with projects serving localhost:80, localhost:443, or custom hostnames from /etc/hosts; those are different host and port bindings.

If another process already uses port 1933, pick a different port:

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

Keep the same port in the agent MCP configuration and in future threadnote invocations.

Seed Skips Files

Skipped files usually matched a secret detector after redaction. Inspect the file manually and either remove the risky content or leave it out of the manifest.

seed-skills --native Fails With [INTERNAL]

Native OpenViking skill ingestion generates skill overviews with the configured VLM provider. If the server log shows an OpenAI quota, rate-limit, or authentication error, run seed-skills without --native. The default mode stores SKILL.md files as searchable resources and does not require native skill overview generation.

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

threadnote stop
threadnote start

Claude MCP Fails While Health Is OK

OpenViking 0.3.12 can be healthy at /health while returning 404 at /mcp. That means the stable server does not expose the native HTTP MCP endpoint.

Use the default stdio adapter:

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

Memories live in ~/.openviking/data, so deleting a branch or worktree does not delete stored memories. The launcher configuration can still point at scripts inside the deleted worktree, though.

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

This is expected. Run with --apply after reviewing the command:

threadnote mcp-install codex --apply

For Cursor:

threadnote mcp-install cursor --apply

This updates the global ~/.cursor/mcp.json file. Restart Cursor or open a fresh agent session after changing MCP config.

For GitHub Copilot in VS Code:

threadnote mcp-install copilot --apply

This updates the VS Code user-profile mcp.json file. Restart VS Code or run MCP: List Servers from the Command Palette after changing MCP config. 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

If Cursor shows an error like expected string, received undefined for Threadnote search, 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 Threadnote 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

Run:

threadnote uninstall --dry-run
threadnote uninstall

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