FAQ

Common issues, each tied to a concrete mechanism or command. For anything missing, open an issue with a log excerpt and reproduction steps.

Install and run

Installer fails with `Error opening file for writing: …vec0.dll`

A previous run left a backend process holding sqlite-vec\vec0.dll. End every Hetu.Api.exe in Task Manager and retry. Newer installers ship a preinstall hook that clears leftovers automatically.

Port 5174 is not reachable from source

Confirm the backend is up: curl http://localhost:5000/api/health.
Run npm install in frontend/ first; if the port is taken, Vite picks another one — check the terminal output.

Changing ports or the data directory

The backend takes --urls for its address and HETU_DATA_DIR for storage; the Vite port is server.port in frontend/vite.config.ts.

Models

Can I use only local models?

Yes. Any OpenAI-compatible server (Ollama, LM Studio, vLLM …) works as a provider — point Base URL at it. If you also embed locally, keep dimensions aligned with Embedding:Dimensions.

Why can't Anthropic do embeddings?

Anthropic exposes no public embedding API, so route the embedding purpose to an OpenAI-compatible provider.

Model errors or timeouts

Use the connection test on the provider page with a chat model first.
The usage detail log shows failed calls with time and source; pair it with the backend logs in logs/.
Local servers have context and concurrency limits: if a compressed session still exceeds them, reduce injected retrieval results per turn.

Indexing and retrieval

Indexing stalls or coverage stays low

Check the Tasks page for failed jobs — the reason is written into the task detail.
Verify the embedding provider with the knowledge base search test.
Switching embedding models changes dimensions, so re-indexing is required.

Semantic search returns poor results

Confirm the item is actually indexed (chunk count in index management).
Make the query more specific; adjust Top-K in the search test to see recall differences.
Structured, longer notes chunk better than scattered bullet fragments.

Code sessions and worktrees

Do worktrees touch my repository?

No. A worktree is a separate directory created by git worktree (default: .hetu-worktrees/ next to the repository) with its own branch and working tree; your main checkout's branch and files are unaffected.

Switching branch mid-session

Workspace and branch are fixed once a session starts, so edits cannot land in the wrong place. Start a new session, or operate branches from the Git panel.

Worktrees pile up

Enable automatic cleanup in Settings → Workspace and set the idle threshold (only merged, clean worktrees are removed). “Clean now” runs it manually; with cleanup off, delete directories yourself or use git worktree remove.

PR panel says gh / glab is missing

PR support reuses the local GitHub / GitLab CLI. The panel prints the platform install command (for example winget install --id GitHub.cli); refresh after installing.

Updates

`Could not fetch a valid release JSON from the remote`

The updater manifest could not be fetched. Upgrade to the latest build; if it persists, open https://github.com/wosledon/Hetu/releases/latest/download/latest.json (slim channel: latest-slim.json) in a browser to confirm reachability, then check connectivity to the mirrors (ghproxy.net and friends).

Performance and size

Does it slow down as data grows?

Lists and statistics run in the database (COUNT + OFFSET/FETCH, GROUP BY aggregates) and status endpoints are briefly cached, so paging and counters stay constant-cost even with tens of thousands of notes.

How large is the database?

Mostly vectors: one per chunk (default 1536-dim float32 ≈ 6 KB). Reduce chunk count or use a lower-dimension embedding model (update the setting and re-index).

Does it work offline?

The application runs fully offline; network access is only needed for cloud models, web search or external MCP servers.

FAQ