Codex config.toml errors and fixes

Find the malformed document, fix duplicate definitions or quoting, then verify startup without removing account or session data.

Error message

One Windows desktop config report prints these parser lines after a path with an unescaped backslash was placed in a double-quoted TOML string:

failed to reload config: C:\Users<user>.codex\config.toml:150:77:
missing escaped value, expected `b`, `e`, `f`, `n`, `r`, `\`, `"`, `x`, `u`, `U`

The report’s path and line number belong to that user’s file; your own error will name its own location. A separate report shows unclosed table, expected ']'. Another macOS report describes a duplicate MCP table that froze the app without a useful UI error. Do not assume a blank window always means a TOML parser error.

When it happens

This guide covers malformed config.toml and configuration-load symptoms in CLI and desktop environments. The exact failure has been reported on specific macOS and Windows builds; it has not been reproduced here on every platform or Codex release. A syntax error inside one file differs from a supported key overridden by a separate trusted layer. The official configuration documentation explains precedence, while the TOML specification defines valid quoting and duplicate-table rules.

Check the active file named in the error before editing a convenient copy. Windows and WSL may use different homes, and an organization or project layer can also affect effective settings. If the CLI gives a path, line and column, inspect that line and the immediately preceding one. A desktop loading screen may require a log to identify the parser failure; an absent on-screen message is not proof of one. Back up the affected file privately before modifying it, keeping account credentials and session data untouched.

Fix it step by step

  1. Locate and preserve the actual file. Record the path, line and column from Error loading config.toml: or failed to reload config:. Use the Codex configuration-location guide if the app names no file, and confirm the affected client and home. Copy the file to a safe local backup before editing. Do not delete the whole .codex directory to repair one malformed TOML document.
  2. Inspect duplicate keys and tables in that same document. A reported minimal reproduction defined [mcp_servers.figma] twice in one file; removing the duplicate and restarting let that reporter use the app again. The TOML specification prohibits re-declaring a table or key in that fashion. Merge the intended values into a single table and retain one value per key. Do not blindly remove repeated-looking double-bracket array-of-table entries, which have separate TOML semantics.
  3. If the error says missing escaped value, check Windows paths. Backslashes inside TOML double-quoted strings introduce escape sequences. For a setting that accepts a path, use a literal TOML string like command = 'C:\Tools\example.exe' or escape each slash in a basic string like command = "C:\\Tools\\example.exe". These are alternative examples, not two keys to paste into one table; replace the placeholder with a verified path for your own setting. The Windows issue reports a \d in a path being read as an invalid escape. Correct syntax does not install a missing executable.
  4. If the error says unclosed table, check its brackets and quoting. One issue reported a mangled non-ASCII project path in a table header; the specific parser text was unclosed table, expected ']'. Check the named line and the line before it for a missing closing bracket or quote. Repair the specific document rather than deleting all project entries. That issue does not establish that every non-ASCII path is unsupported.
  5. Separate syntax from setting validity. A document can parse as TOML yet contain an unsupported Codex key or value. Compare the intended option against the current configuration reference. The CLI command reference documents runtime --strict-config; it is not a standalone offline validator and can start an actual client operation. Check your installed command’s help and choose a harmless validation context rather than assuming an old flag still works.
  6. Save a minimal correction and restart the affected client. Change only the implicated block, then fully quit and reopen the CLI or desktop app. If startup succeeds, verify the configured behavior still works; the absence of a parse banner does not prove that an MCP server or other integration is functioning. If the error moves to another line, preserve the new message and handle that line. A duplicate across different supported configuration layers can be normal precedence, so do not merge files simply because they share a key name.
  7. Confirm the original symptom is gone. For CLI, check that it can start without the config error. For desktop, confirm that a new chat can be sent rather than judging only by the visible window. A macOS issue described a window becoming unresponsive after duplicate tables, while a Windows issue described a startup loading screen after an invalid path string. Keep those observed outcomes distinct from a universal Codex behavior claim.

Still not working?

  • If no parser error exists, revisit the diagnosis. A blank window or setup loop can have other causes; save the app build and relevant log before continuing to change config.
  • If the TOML parses but a configured MCP server fails, follow MCP startup troubleshooting with that server’s exact error. A syntax repair does not establish network or authentication success.
  • If desktop and CLI disagree, compare their active config paths and layers. Retain the working backup and restore it if a speculative edit makes startup worse.

FAQ

Can a duplicate MCP table freeze the Codex app without an error?

One macOS report describes exactly that after the same [mcp_servers.*] table appeared twice in one file. It is a reported outcome on a specific build, not proof that every frozen window is a duplicate-table problem. Inspect the active file or log before editing.

Why does a Windows path break config.toml?

In a TOML basic string, an unescaped backslash starts an escape sequence. The Windows report included missing escaped value after an invalid sequence in a path. Use a literal single-quoted string or double the backslashes in a double-quoted string, for a setting that accepts that path.

Does valid TOML mean my Codex setting is supported?

No. TOML syntax and Codex’s configuration schema are separate. Consult the current configuration reference for the key, type and allowed values, then test the intended behavior in the affected client. Do not treat a parser’s success as proof an MCP integration works.

Compare another message in the Codex error guide library. First check whether this is a Codex service-side problem → View live Codex status.

Sources

Each source lists what it is used to support. Sources are re-read on the review schedule, not continuously.

How this page is checked
Evidence level
Reported - based on public reports, not reproduced here
Last reviewed
2026-10-02
Content updated
2026-10-03
Full version scope
Reported on Codex App 26.303.1606 (806) on macOS, and on Windows app builds 26.803.5235.0, 26.808.x and 26.820.7780.0, among others opened. Other versions and platforms have not been documented as affected, and no fix version can be named.
Symptoms indexed
  • The app starts but a new chat cannot be sent
  • There is no error message anywhere in the interface
  • It started right after you edited config.toml
  • Removing the duplicate block and restarting fixes it immediately
  • On the CLI, a line such as 'Error loading config.toml: <path>:<line>:<column>: <parser message>' appears and the client will not start
  • On the desktop app, the window stays on a loading screen or loops setup with no on-screen error

Reviewer note

Official configuration references and original issue reports re-read on 2026-10-02. Reported outcomes are not a claim of cross-platform reproduction.

Last updated: