Troubleshooting
Most problems are one of a few causes. Find the message you saw below.
Setup
The server cannot find my project
The server refuses to guess. It uses LOCALEXEC_ROOT, else the git top-level of its working directory, else a directory containing .localexec.json. Register with uv run --project, not --directory, or set LOCALEXEC_ROOT for the project. See Register with Claude Code.
unknown key(s) in .localexec.json
Typos in the config are rejected on purpose. The message names the keys. Compare them with the key table.
ollama_url in the project config must point to this machine
A project file cannot send your code to another host. To use another server, set the LOCALEXEC_OLLAMA_URL environment variable.
Ollama
cannot reach Ollama at ... (is it running?)
Start Ollama and check ollama_url. Run the status tool for the exact reason.
status reports the model is not installed
Run ollama list. Create the model as described in Create the model, or set ollama_model to one you have.
Ollama request timed out
The first request loads the model, which can be slow. Raise request_timeout, or reduce the prompt with fewer context files or symbols.
Refusals before the model runs
project is not a git repository
Run git init in the project. localexec uses git to detect unrelated changes.
N unrelated uncommitted file(s)
Tracked files outside files_to_edit have changes. Commit or stash them, or include them in files_to_edit. This keeps a task's diff separate from your own work.
task_id already used
Pick a new id, or run revert_task on the old one. Ids of tasks that changed no files, such as blocked ones, can be reused.
Results
blocked: the files do not fit
The files to edit alone exceed the prompt budget. Split the task, pass symbols instead of whole files, or raise prompt_budget_tokens within the model's num_ctx.
edit_failed again and again
The model's SEARCH text did not match or the reply was malformed. Make the spec more exact, quote the lines to change, use symbols, and shrink the task.
failed with failed_check: standards
A function or file is over its limit. Extract helpers, or split the file as its own task. A file over the maximum is not retried.
changed on disk while the model was working
Something edited a file in the meantime, such as an editor auto-formatting on save. Nothing was written. Run the task again.
revert_task skipped files
Those files were edited after the task. Review them, then pass force if you want the original content back.
Slowness
A task is moved to the background
Claude Code can move long tool calls to a background task after about two minutes. Select fast checks with the checks parameter and use scoped checks. See Slow check suites.