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
- Locate and preserve the actual file. Record the path, line and column from
Error loading config.toml:orfailed 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.codexdirectory to repair one malformed TOML document. - 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. - 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 likecommand = 'C:\Tools\example.exe'or escape each slash in a basic string likecommand = "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\din a path being read as an invalid escape. Correct syntax does not install a missing executable. - 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 wasunclosed 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. - 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. - 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.
- 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.
Related errors
- Codex MCP startup failed when configuration loads but a server cannot start.
- Codex config location to find the active file in the affected environment.
- Codex command not found if a terminal cannot launch the CLI at all.
- Codex session stuck when startup succeeds but a particular session stalls.
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.
Reported configuration-loading symptoms; see the issue for the specific environment and reproduction.
Reported configuration-loading symptoms; see the issue for the specific environment and reproduction.
Reported configuration-loading symptoms; see the issue for the specific environment and reproduction.
Blank window from a duplicate key across config layers (openai/codex #40855, closed)
Reported configuration-loading symptoms; see the issue for the specific environment and reproduction.
Official configuration precedence
Separate config layers may override values.
Official configuration reference
Key names, types and log configuration.
Official CLI command reference
Runtime --strict-config support.
Duplicate table/key restrictions and basic versus literal strings.
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.