Fix Codex unknown variant default: remove service_tier or update Desktop¶

Audience: a service_tier configuration error blocks new threads

If a new thread fails with this message, do not choose fast or flex at random:

invalid configuration: unknown variant `default`,
expected `fast` or `flex` in `service_tier`

If you explicitly added service_tier = "default" to config.toml, back up the file and remove that line. If the setting is absent or removal does not help, update Codex Desktop itself and fully restart it. The likely boundary is a version mismatch between Desktop's embedded app-server and newer model or service-tier metadata.

Key Points¶

Remove an explicit service_tier = "default" while diagnosing the failure
Suspect Desktop's embedded app-server when no user-config line exists
Do not force fast or flex merely to silence the parser error

Why an app can reject `default`¶

Official Codex issue #27297 reports the same error immediately after a Desktop update, even after the user removed every service_tier entry from config.toml. In that environment, the desktop bundle was still launching an older embedded app-server while a newer standalone CLI and model metadata existed on the machine.¹

Meanwhile, the current Codex config.schema.json describes service_tier as an optional value and gives default, priority, flex, and legacy fast as examples.²

The error therefore does not prove that default is universally invalid. It points to a likely mismatch between the component producing the value and the component parsing it.

Recovery steps¶

1. Back up the active configuration¶

The normal CLI file is $CODEX_HOME/config.toml, usually ~/.codex/config.toml when CODEX_HOME is unset.

cp ~/.codex/config.toml ~/.codex/config.toml.bak
rg -n '^service_tier\s*=' ~/.codex/config.toml

On Windows, first identify the CODEX_HOME that the failing app actually uses. Do not edit a different .codex directory based on a guessed path.

2. Remove an explicit `default` value¶

Only if you added this line, comment it out or remove it and restart:

service_tier = "default"

The setting is optional, so removing it returns selection to the app. Replacing it with fast or flex is not a neutral parser fix; those choices can affect speed, eligibility, and usage characteristics. Use an explicit tier only when you intend that behavior and have checked the current product guidance.

3. Update Codex Desktop itself¶

If the line is absent and the error still appears, updating only the terminal CLI is insufficient. Desktop can launch a separate binary embedded inside the app bundle.

Update through Codex Desktop or the store that installed it
Fully quit the app and stop remaining Codex processes
Relaunch and test a new thread

On macOS, you can compare the embedded and standalone binaries:

/Applications/Codex.app/Contents/Resources/codex --version
codex --version

Different version numbers do not prove a defect by themselves. An older embedded version immediately after this parser error is useful evidence of mismatch.

4. Interpret doctor results correctly¶

codex doctor --summary

A successful result does not prove the desktop app-server is healthy. If the terminal and Desktop use different binaries, one can load configuration correctly while the other fails.

What to record if it still fails¶

Compare these four details with existing reports:

The full error message
The Codex Desktop build shown in About
Output from the standalone codex --version
Whether config.toml contains any service_tier entry

Also mention if the model selector is unavailable. Issue #27297 reports that symptom together with the service-tier parser error.¹

Fixes to avoid¶

Forcing fast: it changes service behavior and does not align incompatible components
Forcing flex: it can select an unintended tier instead of fixing the parser boundary
Deleting all of .codex: it can remove sessions or authentication and still reproduce with the same embedded build
Updating only the CLI: Desktop may continue to run its own bundled binary
Hard-coding a model: this can mask, rather than repair, model-catalog and parser drift

FAQ¶

Is service_tier = \"default\" always invalid now?

No. The current official configuration schema lists default as an example. The reported failure occurs when an older parser receives a value from a newer metadata path. Remove the explicit line in the affected setup and align the desktop package.

Why do I get the error when config.toml has no service_tier line?

Desktop state, model metadata, or the app-server protocol can carry the value through other paths. The official issue reproduces the error without a user-config entry.

Should I choose fast or flex?

Not merely to silence the error. Return to an unspecified tier and update Desktop first. Choose an explicit tier only when you need it and understand the current eligibility and usage behavior.

Summary¶

Remove an explicit service_tier = "default" after backing up the config
If no line exists, investigate drift between Desktop's embedded app-server and model metadata
Update and fully restart the desktop app; inspect CLI and Desktop separately
Do not force a tier or delete all local state as the first response