Codex Desktop stuck on a white screen or spinner: how to fix it on Windows and macOS

You open Codex Desktop and it sits on a white screen with the spinner going, or the window was working fine and suddenly turned white with the logo in the middle. Reinstalling almost never helps. In September 2026 this symptom showed up with three different causes in the official openai/codex repository, and in none of them do you lose work: what hangs is the interface, not the agent.

Which of the three white screens do you have?

When the screen turns white tells you the cause. Match it against the table and jump to the right section.

When it happens	Likely cause	What to do
Right at launch, after updating to build 26.924 on Windows	Startup failure between the window and the codex.exe process (app-server)	End only the child codex process
Mid-session, after a while, on Windows or macOS	Rendering process hung, holding 3 GB of memory or more	End only Codex (Renderer)
Always, even after reinstalling	~/.codex/config.toml corrupted, full of NUL bytes	Rename the file

Stuck on the spinner right after updating: how do you get past it on Windows?

End only the child codex process while the spinner is on screen. The main app spawns a new one right away and the interface loads with your projects and chats.

The case is documented in issue #48333, opened on Sep 26, 2026 with package OpenAI.Codex 26.924.1866.0, and confirmed by other users on build 26.924.2738.0 as well. The log shows the internal MCP server timing out:

MCP server startup failed server_name="codex_app" error="timed out awaiting tools/list after 10s"

The person who opened the issue had already tried Windows Repair and Reset, uninstalling and reinstalling, a fresh .codex, and removing config.toml. None of it helped, so skip those steps.

What to do:

1. With the spinner on screen, open Task Manager, expand the app's group and end the child process named Codex (reported in issue #48578).
2. Or do the same from PowerShell, as one user recorded in #48333:

   Stop-Process -Name codex -Force

   Heads up: this ends every codex process, including a Codex CLI session open in another terminal.
3. If it doesn't come back, try the other path reported in the same issue: end the app's main rendering process. To list the candidates:

   Get-CimInstance Win32_Process -Filter "Name='ChatGPT.exe'" |
     Where-Object CommandLine -like '*--type=renderer*' |
     Select-Object ProcessId, CommandLine

   End the one with the lowest --renderer-client-id using Stop-Process -Id <PID>. According to the report, the window recovers in about 5 seconds.

This is a per-launch workaround: the next time you close and reopen, the spinner tends to return until a fixed build ships. As of Sep 28, 2026, none of the issues had a reply from an OpenAI maintainer.

It went white in the middle of work: did the agent stop?

No. In these reports the agent keeps running in the background, and only the window stops painting. End the rendering process and the interface comes back without closing the app.

On macOS, issue #46641 (ChatGPT app 26.915.31945) shows the Codex (Renderer) process reaching about 120% CPU and 3.2 GB of memory, peaking at 4.7 GB. On Windows, #47110 (build 26.915.4065.0) logs the renderer at 2,973 MB while the session kept working from the phone app.

On macOS: open Activity Monitor, find Codex (Renderer) with high CPU and Force Quit only that one. From the terminal:

ps aux | grep -i codex | grep -i renderer
kill <PID>

On Windows: use the same Get-CimInstance command from the previous section and end the renderer using the most memory.

The #46641 report is clear: ending only the renderer restores the screen instantly, with no need to quit ChatGPT. The problem tends to come back after a while.

White even after reinstalling: what survives a reinstall?

The ~/.codex folder. Uninstalling the app doesn't delete it, and a corrupted config.toml inside it keeps the screen white on any fresh install.

Issue #44374 documents it: config.toml was 2,700 bytes, all 0x00. Codex Desktop only showed white; it was the Codex CLI that revealed the error:

Error loading config.toml:
C:\Users\<username>\.codex\config.toml:1:2701
key with no value, expected '='

What to do:

1. Check the first bytes of the file. On Windows:

   Format-Hex "$env:USERPROFILE\.codex\config.toml" | Select-Object -First 2

   On macOS or Linux:

   head -c 64 ~/.codex/config.toml | xxd

   All zeros (00 00 00 ...) confirms the corruption.
2. Rename the file instead of deleting it:

   Rename-Item "$env:USERPROFILE\.codex\config.toml" config.toml.bak

   mv ~/.codex/config.toml ~/.codex/config.toml.bak

3. Open the app again. In the report, the interface came back immediately and projects and history were still there. Redo your settings in a new config.toml.

Keeps coming back, on one machine only: how do you find the trigger?

Test with a clean ~/.codex folder by renaming the old one. If the app stabilizes, the trigger is somewhere in the old state, not in your account or the build.

That's how #46641 isolated the problem: the same build worked on a MacBook and failed on a Mac mini, a new macOS user on that same Mac mini worked, and clearing ~/Library/Application Support/OpenAI/Codex didn't help. With an empty ~/.codex, the app went back to normal.

# macOS / Linux, with the app closed
mv ~/.codex ~/.codex-backup

# Windows (PowerShell), with the app closed
Rename-Item "$env:USERPROFILE\.codex" .codex-backup

Don't delete the old folder: your sessions (sessions/) and history live there. The same report says moving a session file that was still referenced made the app show "unable to restore". Bring back what you need a little at a time, and leave out interface state files such as .codex-global-state.json.

Need to work right now: can you use Codex without the window?

Yes. The Codex CLI doesn't depend on the Desktop window. In issue #48578, with the app stuck on the spinner, codex 0.157.0 in the terminal kept accepting and answering prompts normally. Before filing an issue, run the local diagnostic and attach the redacted version:

codex doctor --json