Codex Background Server Has Incompatible Feature Settings: What to Check

The Codex message “Background server has incompatible feature settings” means the CLI and the shared server disagree about settings required for that session. Compare both versions before changing a feature flag. If versions match, a saved server override may still explain the mismatch. A successful restart message alone does not show that the next session will work.

This guide covers the terminal CLI’s compatibility dialog, including api_key_model_discovery. It is different from a desktop app that cannot load workspace settings or a Windows process that cannot find its executable. The checks below do not require a paid model call.

Sources were checked on October 16, 2026. They include public incident reports and a maintainer’s scoped fix statement. Our local verification checked command availability in CLI 0.154.0; we did not reproduce the reported 0.161.0 failures or interrupt a live daemon to test a repair. Ofox publishes this diagnostic guide, but switching API providers is not a demonstrated solution to this startup negotiation.

Identify the exact mismatch

The dialog can request that api_key_model_discovery be enabled or disabled. That direction matters. Do not copy a flag from someone else’s screenshot before reading your own message.

Write down these four facts:

The reports in issue #51758 describe version skew in both directions. A newer CLI and an older daemon can be as relevant as an older CLI and a newer daemon. The thread includes a maintainer statement that 0.162.1 addresses ordinary launches being blocked by differing default features. The maintainer recommends updating the CLI to 0.162.1 or later through your installation channel. That is a fix for that documented behavior, not a promise that every explicit override or daemon error disappears.

Collect versions without changing the service

Run these in the terminal where the failure happens:

codex --version
codex app-server daemon version
codex features list

The daemon version command is intended to report client/server version information. Record the actual fields returned by your build, including whether a daemon is running; do not replace missing values with the CLI version. If a subcommand is unknown, inspect help for the installed version rather than treating an unsupported diagnostic command as a second daemon failure:

codex app-server daemon --help
codex features --help

On macOS or Linux, inspect command resolution with command -v codex. In PowerShell, use Get-Command codex | Select-Object Source. These show the command your current shell resolves; they do not enumerate every executable bundled inside a desktop app.

An update performed in npm will not necessarily change the binary selected from a different package manager. Use the updater associated with the installation you actually run. Verify its version afterward in a fresh terminal. Do not reinstall every package manager’s copy at once.

Read the results as a decision table

Version equality is useful evidence, not a complete health check. Issue #52085 reports a same-version startup mismatch, so “the numbers match” is not a sufficient stopping point. That report also shows a disabled restart choice because the server was not managed by Codex. If your dialog says the same, use the offered temporary path or coordinate with the server operator; do not assume the CLI can restart an independently managed service.

Choose a recovery path based on its effect

The affected versions offered a choice to run without the daemon for that invocation, restart with the displayed settings, or cancel. Use the choices actually shown by your installed client; option labels and supported flags can change.

For a time-sensitive task, the offered temporary path may let you continue without immediately changing the shared service. It is not a permanent repair, and it does not prove that all remote or background workflows are available without the daemon. Preserve the resume/fork intent of your task instead of accidentally starting unrelated work.

If you choose a persistent restart, first save work and account for other clients using the same service. Read the complete settings proposed by the dialog, not only the flag named in the first line. Afterward, verify the effective state and start a fresh session. Do not describe a restart as harmless merely because it is a normal CLI command.

Why a restart can succeed while the mismatch remains

Issue #51787 documents a specific 0.161.0 case: a restart command accepted an enable flag but retained a conflicting saved override. The report’s interactive recovery path changed the saved state and allowed a subsequent session to start. The issue was closed when checked, but closure alone is not a version-by-version guarantee for your installation.

The important distinction is process lifecycle versus effective settings. The process can restart successfully while reading the same persistent setting that caused the conflict. Repeating the identical restart is therefore not a diagnostic plan.

The reported file is under the effective Codex home directory at app-server-daemon/settings.json. If you use a custom CODEX_HOME, inspect that home rather than assuming ~/.codex. A named configuration profile does not by itself establish a separate home directory. Read only the relevant feature override, and do not publish the whole settings file. Compare it with codex features list and the direction requested by the dialog.

For example, a saved false value and a session requiring true are a meaningful discrepancy. They do not authorize deleting the file: other settings may belong to remote management or other users of the service. Keep a private backup before an intentional change, use supported recovery controls and retain the original values for rollback. If ownership is unclear, stop and ask the person managing the server.

What not to change as a first response

• API credentials: the reported mismatch can happen before a model request. Deleting authentication state does not establish that the server’s feature configuration changed.
• The model name: an incompatible setting is not the same as model_not_found. Confirm the error stage before editing model configuration.
• All Codex data: removing the entire home directory discards unrelated state and makes before/after diagnosis harder.
• Security settings: broader sandbox or file access does not demonstrate compatibility between the CLI and daemon.

For the wider configuration model, use the Codex config guide. If the actual failure is a Windows path or missing runtime, use the app-server startup guide. A Desktop workspace-loading banner is covered by the workspace settings diagnostic.

Verify the repair in a new session

A useful acceptance check has three parts:

1. Recollect the versions and relevant feature state. Note what changed and what did not. A new CLI version alone is not proof that the running server changed.
2. Launch a fresh session through the originally failing path. Reaching the normal prompt without the compatibility dialog checks startup negotiation. You do not need to send a paid model request to verify this stage.
3. Verify the original workflow separately. If you need to resume an existing task, use that intended task and check its state before issuing new work. Background/remote behavior should be checked only when it is part of your workflow.

If only the temporary no-daemon path works, record workaround active; shared-server mismatch unresolved. If a fresh ordinary launch works but another client fails, record the regression rather than calling the repair complete.

Use this compact record when escalating:

Observed time and timezone:
Operating system and install method:
CLI version / resolved executable:
Daemon version / running or unavailable:
Exact required feature and enabled-or-disabled direction:
CLI feature value / relevant saved server override:
Intentional overrides: yes / no / unknown
Active or queued shared work: yes / no / unknown
Action attempted and effective state afterward:
Fresh ordinary launch / temporary path / original workflow result:

Review the record for credentials and private paths before sharing it. The useful evidence is the mismatch and the tested outcome, not a dump of your configuration. A successful repair is a fresh launch with the intended state preserved, not simply an exit code of zero from a restart.