Local model failures can occur before a prompt ever reaches the model. Codex needs the selected provider's API to answer before it can run a local task, so restoring a stopped server can resolve a connection failure without changing the model or repository settings.
A model list establishes that the server is reachable, and a text response establishes that it can generate an answer. Repository work also depends on tool calls, so a model that answers ordinary questions can still fail to complete a Codex task.
You need an existing Ollama installation, a downloaded local model, the Codex CLI, and curl. The error from your failing task determines where diagnosis starts; there is no need to create another task or change project files to reproduce it.
Steps to troubleshoot local models in Codex:
- Match your existing Codex error to the affected component.
No running Ollama server detected or a refused connection points to the listener. A missing-model error points to the inventory or model name. An HTTP error from /v1/responses, an unsupported tool, or a context-limit error points to API or model compatibility. A message saying the chat uses Ollama but the current provider is OpenAI points to provider selection. Only the matching checks and corrections are needed before the final retry.
- Check the Ollama listener if the task reports a connection failure.
$ curl --fail --silent --show-error http://localhost:11434/v1/models curl: (7) Failed to connect to localhost port 11434 after 0 ms: Couldn't connect to server
This refused connection places the fault at the listener or endpoint layer. Ollama normally listens locally on port 11434. For a custom endpoint, the URL must match the provider selected by Codex. An HTTP error from a reachable server is a different signal from a refused connection.
Related: How to route Codex to a local model - Start the stopped Ollama server in a separate terminal.
$ OLLAMA_CONTEXT_LENGTH=65536 ollama serve
The server stays attached to that terminal. The context setting gives Codex room for its instructions and tool results; a larger context also requires more memory. If Ollama is managed by its desktop app or a service manager, starting that existing instance restores the listener instead. An address-in-use error means another process already owns the port; it does not justify stopping an unrelated service.
Related: How to use Ollama models with Codex - Inspect the model inventory when the listener responds or the task reports a missing model.
$ curl --fail --silent --show-error http://localhost:11434/v1/models {"object":"list","data":[{"id":"qwen3:4b-instruct-2507-q4_K_M","object":"model","created":1793520913,"owned_by":"library"}]}
A returned model list confirms API reachability. The model argument must match a returned id exactly, including its tag. An empty list or absent ID is an inventory problem. A downloaded model in another provider's storage is not available to this Ollama instance.
- Replace an unavailable or incompatible model in your original Codex command.
-m qwen3:4b-instruct-2507-q4_K_M
For the inventory above, this model option selects the installed tool-capable model. If the intended model is not installed, downloading it belongs to provider setup. Changing the per-run argument avoids replacing saved routing for other projects.
Related: How to use Ollama models with Codex
Related: How to route Codex to a local model - Test text generation if the model is listed but the task fails during inference.
$ curl --fail --silent --show-error http://localhost:11434/v1/responses \ --header 'Content-Type: application/json' \ --data '{"model":"qwen3:4b-instruct-2507-q4_K_M","input":"What is 17 plus 25? Reply with just the number."}'
The model value must name your installed model. A completed response containing 42 establishes text generation through the API used by Codex. A model-not-found response requires the inventory correction. An unsupported Responses endpoint requires an Ollama version that supports that API. A text answer alone does not establish tool support.
Related: How to use Ollama models with Codex - Inspect the model's capabilities if text generation works but tool calls fail.
$ ollama show qwen3:4b-instruct-2507-q4_K_M
The model name must match your selected model. The Capabilities section needs tools for repository tasks. If it is absent, the per-run -m correction above needs a model that lists tools. A model can advertise a large context limit while the server allocates less; Ollama recommends at least 64k tokens for Codex. Context-limit failures require a larger server allocation within the available memory.
Related: How to use Ollama models with Codex
Ollama context settings - Add an explicit provider override if Codex reports a provider mismatch.
The per-run arguments --oss --local-provider ollama select the local provider. In Codex CLI 0.166.0, a run can still report that the chat uses Ollama while the current provider is OpenAI. Adding -c 'model_provider="ollama"' to the original command resolves that mismatch without editing saved settings.
- Rerun your originally failing Codex task.
Repository content can reach the selected provider, and Codex tools can execute commands under the active approval and sandbox policies. A narrow working directory does not itself restrict all file or network access.
The run header should identify the intended model and provider, and the original request should finish without its previous error. For repository tasks, a successful tool call and the requested result establish recovery beyond text generation. Loading the model and processing Codex instructions can take minutes. A workspace-trust error after connection recovery belongs to that later layer.
Related: How to fix the Codex trusted-directory error