Troubleshooting

Search or indexing seems off

The semantic index rebuilds incrementally on startup and as files change. If results seem stale, let the index reach a ready state before asking an agent to rely on indexed search. If the local embedding model is unavailable, V3Code can still use lexical search; do not treat that fallback as a completed semantic index.

The index keeps firing and the editor feels slow

Symptoms. The editor becomes laggy or stuttery while the logs repeat file-read errors. Typical messages say that a path is actually a directory, or that a file such as AGENTS.md.git does not exist.

An occasional bad-path error is usually harmless. A repeating retry loop is not: it can keep walking the wrong tree, generate log noise, and spend work on files that are not part of your active project. Search results may also point to an old copy of the code, while find_text appears to miss files that you know exist.

The most common cause is a wrong or stale workspace root. For example, the folder that contains the current work may never have been attached, while an older copy or a large neighboring repository remains attached. File-watcher churn can then surface directory paths or malformed paths as though they were source files.

Fix it in this order:

1. Run index_health with rebuild enabled to clear stale indexed chunks.
2. Check the reported paths on disk. Confirm that directory paths are directories and that malformed paths such as AGENTS.md.git do not exist.
3. Attach the folder that actually contains the current project. Use open_project with mode add if you intentionally need a multi-root workspace.
4. Run a search for a symbol or phrase that only exists in the current project. The top results should come from the live root, not an older copy.
5. If an attached root is obsolete, detach it with close_project so duplicate-looking results cannot come from both the stale and current trees.

Do not use a green index_health result as the only proof. A healthy index can still be indexing the wrong folder. A correct search hit from the expected root is the stronger verification.

Rule of thumb: when indexing is noisy and the editor slows down, first verify which workspace roots are attached. The index may be repeatedly walking a stale tree rather than finding a problem in your code.

An external agent is not ready

V3Code can find an agent launcher on your PATH before that agent has completed its own setup or sign-in. Launcher available only means V3Code found a way to start it.

1. Open the agent’s setup details and use its documented setup or sign-in flow.
2. Review the command V3Code stages in the integrated terminal before you press Enter. V3Code does not run the command, copy credentials, or complete sign-in for you.
3. Open a new agent chat after setup. If you changed projects, open the target folder in V3Code first, then start the new chat there so its workspace context and index match.

Read the full Agent Client Protocol guide for the supported setup flow and workspace boundaries.

An MCP connection broke after an update

Open Settings → Expose V3Code. If the Codex connection shows an older fixed-port definition, choose Repair. For other clients, copy the current stable definition again instead of saving the direct loopback URL as a permanent port.

The current endpoint is available under Current direct endpoint (advanced) and in ~/.v3code/endpoint.json. It can change when V3Code updates or when multiple builds run.

Debug cannot collect runtime evidence

The Debug evidence sink requires one trusted workspace folder. Multi-root or untrusted workspaces continue with ordinary read, command, and test tools but do not collect the loopback runtime stream. Open a single folder and trust it before retrying if that stream is necessary for the reproduction.

A local model call fails

If you’re using Ollama and a call errors out, it usually means Ollama is powered off — start it and retry. For built-in local inference, make sure the model finished downloading.

A free model will not run

The beta free-auto connection needs no API key. Its upstream free models can be busy, rate-limited, or withdrawn. Retry later or choose a different configured connection; adding an unrelated API key will not restore free-model capacity. See free agent models.

Do not confuse that connection with Auto orchestration tiers that use configured providers. If a selected tier explicitly requests a provider key, check the connection and tier you selected before entering credentials.

Cloud sync shows an error

Cloud sync state is shown in the status bar. A paused or errored state doesn’t affect local work — your local index and memory keep running.

I do not see a new release

Check the current version on the download page. If it is newer than your installed build, quit V3Code and use the platform’s latest installer or archive. Apple Silicon Macs and Windows x64 normally receive update prompts; Intel Macs and Linux x64 are manual downloads today.

If a newer build still will not install, email support@v3code.dev with your operating system, CPU, installed version, and a screenshot of the message. Leave API keys, account tokens, and project files out of the report.