Skip to content

Codex CLI Won't Start: Fix unknown variant xhigh Quickly

Codex CLI Complete Guide

Target Audience

  • Developers using Codex CLI 0.50.0
  • Anyone hitting the unknown variant xhigh error at startup
  • Those who want the fastest possible fix

When running Codex CLI, you may encounter an immediate crash during configuration loading.

Error loading configuration: unknown variant `xhigh`, expected one of `minimal`, `low`, `medium`, `high`
in `model_reasoning_effort`

This article provides a copy-paste fix and prevention tips for team environments.

What's Happening

Key Point

This is a pre-API, pre-network issue. The config schema validation is failing.

Codex CLI loads configuration files (user settings and project settings) at startup. The model_reasoning_effort field is strictly validated as an enum, and if the CLI encounters an unrecognized value (like xhigh), it fail-fasts immediately.

This means "the schema check fails before any model query," so investigating API keys or network won't help.

Quick Fix (Copy-Paste Solution)

Replace xhigh with high to recover. Target locations:

  • User settings: ~/.codex
  • Repository Team Config: .codex
# Bulk replace xhigh with high
grep -RIl --exclude-dir .git -E 'model_reasoning_effort *= *"xhigh"' ~/.codex .codex 2>/dev/null \
| while read -r f; do sed -i 's/model_reasoning_effort *= *"xhigh"/model_reasoning_effort = "high"/g' "$f"; done

# Retry
codex /model

Verification

If codex /model runs successfully, you're recovered.

Troubleshooting When It Doesn't Work

Environment Variable Override

An environment variable may be injecting xhigh instead of config files.

env | grep -i -E 'codex|reason|effort|openai'

If you find a value containing xhigh, unset it and retry.

unset CODEX_MODEL_REASONING_EFFORT
codex /model

Config Located Elsewhere

Use this command to find the "culprit file":

grep -RIn --exclude-dir .git --exclude-dir .venv --exclude-dir node_modules \
  -E 'model_reasoning_effort|xhigh' ~ 2>/dev/null | head -50

Prevention

Block in CI

xhigh contamination often happens through template swaps or copy-paste. Block it cheaply in CI.

grep -RIn -E 'model_reasoning_effort *= *"xhigh"' .codex ~/.codex 2>/dev/null && exit 1 || true

Pin CLI Version

"New template, old CLI" alone can break everyone's startup. Pin codex-cli via npm/package manager and update deliberately.

Summary

Key Takeaways

  • unknown variant xhigh is an enum validation failure during config loading
  • Replace xhigh with high for the quickest recovery
  • CI checks and CLI version pinning prevent recurrence