Common Codex + Ollama local model errors: troubleshooting order, causes, and fixes

When Codex fails to use a local model through Ollama, the error often looks like a Codex problem. In practice, it is usually one of a few smaller issues: Ollama is not running, the model name is wrong, Codex is still using the cloud provider, localhost points to the wrong environment, or the local model cannot handle the task.

The safest way to debug is not to change five settings at once. First make sure Ollama can answer, then confirm Codex is really using Ollama, and only then tune model size, context length, and tool-use behavior.

Confirm the Correct Integration First

The usual local setup has three layers:

Ollama runs the local model.
Codex connects to Ollama as a local provider.
Codex sends coding tasks to that model.

For example:

1
2
3


ollama serve
ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b

Then start Codex with the Ollama provider enabled, depending on your Codex version and supported options:

1

codex --oss --local-provider ollama

If your Codex build does not recognize these flags, do not keep retrying the same command. Check the local help first:

1
2


codex --help
codex --version

Minimal Troubleshooting Order

Use this order before changing configuration files:

1
2
3
4
5
6


ollama --version
ollama list
ollama run qwen2.5-coder:7b
curl http://localhost:11434/api/tags
codex --version
codex --help

If ollama run fails, fix Ollama first. If curl cannot reach port 11434, fix the service. If Codex does not show local-provider options, update Codex or use the supported configuration path for your version.

Error: ollama Command Not Found

This means Ollama is not installed or its executable is not in PATH.

On Windows, install Ollama from the official installer, then open a new PowerShell window:

1
2


where.exe ollama
ollama --version

If the command is still missing, restart the terminal or Windows. On macOS and Linux, confirm the shell can see ollama before touching Codex.

Error: Ollama Service Is Not Running

Codex cannot connect to a local model if the Ollama service is down.

Check:

1

curl http://localhost:11434/api/tags

If there is no response, start the service:

1

ollama serve

On Windows, the desktop Ollama app may manage the service for you. If you run it manually and also have the app running, avoid starting two conflicting instances.

Error: model not found

Ollama model names must match exactly.

Check installed models:

1

ollama list

Pull the model you want:

1

ollama pull qwen2.5-coder:7b

Then test it outside Codex:

1

ollama run qwen2.5-coder:7b

Do not guess the tag. qwen2.5-coder and qwen2.5-coder:7b can behave differently depending on what is installed locally.

Error: Codex Is Not Using Ollama

If Codex still asks for cloud login or API credentials, it may not be running in local-provider mode.

Check:

1

codex --help

Look for flags or config entries related to local providers, OSS mode, or Ollama. If the current version has changed its option names, use the command help as the source of truth.

Also check project-level Codex configuration. A global config, provider setting, or leftover environment variable can make Codex use another provider.

Error: unknown option

This usually means the tutorial you copied targets a different Codex version.

Run:

1
2


codex --version
codex --help

Then either update Codex or adapt the command to the options your version supports. Do not assume every blog post, README, or screenshot uses the same CLI build.

Error: localhost Points to the Wrong Place

This happens often with WSL, Docker, remote terminals, and Windows apps.

If Ollama runs on Windows but Codex runs inside WSL, localhost inside WSL is not always the Windows host. You may need the Windows host address, WSL networking bridge, or an explicit bind address.

Test from the same environment where Codex runs:

1

curl http://localhost:11434/api/tags

If this fails inside WSL but works in Windows PowerShell, the problem is networking, not the model.

Error: 401, API Key, or Authentication

Local Ollama normally does not require an OpenAI API key. If you see API-key-style errors, Codex may still be using a cloud provider or OpenAI-compatible endpoint.

Check the provider, base URL, and environment variables:

1
2


$env:OPENAI_API_KEY
$env:OPENAI_BASE_URL

For local-only runs, remove conflicting variables in the current session:

1

Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue

Only do this if you understand which provider you want Codex to use.

Error: Request Hangs or Never Responds

Local models can be slow, especially on CPU or small GPUs.

Check:

Is the model too large for your machine?
Is Ollama downloading or loading the model?
Is the GPU actually being used?
Is the prompt too long?
Is Codex asking for tool-heavy reasoning that the model cannot follow?

Start with a smaller coding model and a tiny task. If a one-line question is slow in ollama run, Codex will also be slow.

Error: context length exceeded

Codex tasks often include files, diffs, logs, and instructions. A local model with a small context window may fail quickly.

Reduce the task:

Ask Codex to inspect one file first.
Remove large logs.
Split the change into smaller steps.
Use a model with a larger context window.
Avoid sending the whole repository when a narrow path is enough.

Error: Tool Calling Is Unstable

Many local models can write code, but tool-use discipline varies. Symptoms include invented commands, ignored output, broken JSON, or repeated loops.

Use local models for:

simple code edits;
explanation and refactoring;
small bug fixes;
local documentation work.

Use stronger cloud models for:

cross-repository refactors;
complex debugging;
security-sensitive reviews;
long tasks that require reliable tool use.

Windows Pitfalls

On Windows, many issues are PowerShell issues rather than Codex issues.

Use:

1
2
3


where.exe ollama
where.exe codex
$PSVersionTable.PSVersion

Avoid copying Bash commands such as:

1

export OLLAMA_HOST=...

Use PowerShell syntax instead:

1

$env:OLLAMA_HOST = 'http://localhost:11434'

If a path contains spaces or Chinese characters, use quoted strings and -LiteralPath when using PowerShell cmdlets.

Recommended Stable Setup

A steady first run looks like this:

1
2
3
4
5


ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b
curl http://localhost:11434/api/tags
codex --help
codex --oss --local-provider ollama

Then test with a small repository and a narrow request:

1

Read this single file and suggest one safe refactor. Do not edit yet.

Once this works, expand to edits, tests, and longer tasks.

Troubleshooting Template

When asking for help, include:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


OS:
PowerShell or shell version:
Codex version:
Ollama version:
Model name:
Command used:
Exact error:
Does ollama run work:
Does curl http://localhost:11434/api/tags work:
Are you using WSL, Docker, or remote SSH:

This makes the real failure point much easier to identify.

FAQ

Is Codex fully offline after connecting to Ollama?

Not necessarily. It depends on your Codex mode, provider configuration, and whether other services are still enabled. Verify the provider instead of assuming.

Can I use Ollama as an OpenAI-compatible base_url?

Some tools support OpenAI-compatible local endpoints; others require a dedicated Ollama provider. Use the mode your Codex version documents.

Are local models suitable for every Codex task?

No. They are useful for privacy, cost control, and small local tasks, but complex tool-use and long-context work may still need stronger models.

Why does the model answer in Ollama but perform badly in Codex?

Chatting is easier than agentic coding. Codex may require planning, file edits, command execution, and output interpretation.

Do I still need an OpenAI API key?

For pure Ollama local runs, usually no. For cloud providers, mixed setups, or fallback modes, yes.

Do I need to restart Codex after switching models?

Often yes. Restarting avoids stale provider or model state during debugging.

Summary

Most Codex + Ollama failures come from service status, model names, provider selection, networking, or local model limits. Debug from the bottom up: Ollama first, then localhost, then Codex provider, then model capability. Once each layer is confirmed, the setup becomes much less mysterious.