# Troubleshooting

## Search or indexing seems off

The [semantic index](/editor/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](/connect/agent-client-protocol) 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](/models/byok) 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](/models/connected-plans#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](https://app.v3code.dev/download). 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](mailto: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.