Codex Crashes on a SUBST Drive? Reopen the Physical Path

If Codex Desktop on Windows opens a project through a SUBST drive and starts showing an empty file browser, repeated ENOENT errors, or crashes, remove that project entry from the Codex sidebar and reopen the same repository through its physical path. For example, replace X:\workspace\repo with D:\codex-subst\workspace\repo.

Keep the SUBST mapping if other tools need it. The important containment step is to give Codex one path identity for the repository instead of opening the alias and physical path together.

This workaround is based on an open Codex issue with an independent reproduction. It is not a confirmed upstream fix, and it does not prove that every Codex crash on Windows comes from path normalization.

Match the Exact Failure Signature

Use this guide only when several of these details line up:

The reported malformed path looked like this:

D:\codex-subst\workspace\repo\R:\workspace

That string is the strongest classifier. A generic ENOENT message is not enough because missing files, stale worktrees, WSL bridges, permissions, and sandbox startup failures can all produce similar errors.

Recover Without Deleting the Repository

First, confirm the mapping in Command Prompt or PowerShell:

subst

Find the row for the drive Codex currently uses. It should map an alias such as R: or X: to a local directory on another drive.

Then recover in this order:

1. Record the alias path and its physical target from subst.

2. Confirm the physical directory exists in File Explorer and contains the expected repository.

3. Finish or stop any command that is actively writing files in the affected task.

4. Remove only the alias-based project entry from the Codex sidebar. Do not delete the directory from disk.

5. In Codex, open the physical path shown by subst.

6. Start a fresh test task in that physical-path project and open Workspace -> Open file.

7. Keep only the physical-path entry in Codex while this upstream issue remains open.

The original report stopped crashing after switching to the physical directory. A second user reproduced the empty file browser and malformed watcher path across multiple repositories under a substituted drive, then confirmed that ordinary Git, terminal, and agent filesystem access still worked. That combination points to Codex's workspace identity and watcher boundary rather than damaged project files.

Why Two Valid Paths Become One Invalid Path

Windows SUBST associates a local path with a virtual drive letter. The alias and physical path can both be valid names for the same directory.

The open issue reconstructs a likely failure using Node's Windows path rules:

const path = require('path').win32;

const physical = 'D:\\codex-subst\\workspace\\repo';
const alias = 'R:\\workspace\\repo';
const relative = path.relative(physical, alias);

console.log(relative);
// R:\workspace\repo

console.log(path.join(physical, relative));
// D:\codex-subst\workspace\repo\R:\workspace\repo

When the two inputs have different drive roots, path.relative() can return a drive-qualified path. If later code treats that result as an ordinary relative segment and joins it to the physical root, the app gets a path that cannot exist.

This mechanism is a strong reproduction of the observed string, but it remains an inference until the Codex maintainers identify the exact code path. Do not patch Codex's installed application files based on this explanation.

Verify the Workaround

The recovery is successful only when all of these observations hold:

1. Codex shows the project under the physical path only.

2. Workspace -> Open file displays the repository tree.

3. Opening a known file succeeds.

4. A new task can read the repository and run a harmless command such as git status.

5. New logs do not contain a path with both the physical drive and SUBST drive joined together.

6. The app remains stable through the workflow that previously triggered the failure.

Check the logs for the exact malformed path, not just the number of errors. Old log entries will remain after the workaround and do not prove the current project is still broken.

Reproduce It in a Disposable Folder

If you need a clean upstream reproduction, do not use a production repository. Create a temporary local folder and map a spare drive letter to it:

New-Item -ItemType Directory -Path C:\codex-subst-repro
git -C C:\codex-subst-repro init
subst R: C:\codex-subst-repro
subst

Open R:\ in Codex, then open the same folder as C:\codex-subst-repro. Test Workspace -> Open file and capture only the relevant watcher error.

When the test is finished, close both disposable project entries and remove the temporary mapping:

subst R: /d

Delete the temporary folder only after you confirm it contains no work you need. A single failing and passing comparison is enough; repeated crashes do not add useful evidence.

Do Not Use Broad Resets for This Bug

Avoid these actions while the repository is healthy at its physical path:

• deleting .git, .codex, conversation databases, or the repository;

• reinstalling Codex before testing one canonical path;

• editing Codex's state database to replace paths;

• removing every SUBST mapping on the machine;

• opening both path spellings again to see which one Codex chooses;

• treating every Windows ENOENT as this same bug.

The containment is intentionally narrow: one repository, one physical path, one Codex project identity.

Separate SUBST From Other Windows Path Bugs

Codex has had other Windows path-normalization reports involving C:\... versus \\?\C:\..., mapped network drives, UNC paths, WSL paths, and sandbox bridges. Those reports support the broader need to compare canonical file identity, but their fixes do not establish that the SUBST composition bug is resolved.

Use the symptom boundary:

• D:\repo\R:\repo in one path: follow this SUBST guide;

• C:\... versus \\?\C:\... on resume: update Codex and check the running-thread normalization fix;

• a network or UNC drive: keep that issue separate from a local SUBST alias;

• commands fail but the file browser works: diagnose the sandbox or shell boundary instead.

Monitor the Upstream Issue With Aident Loadout

Start with the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then give your agent a bounded, read-only check:

Check Aident Loadout authentication and Vault status. Discover the current GitHub issue-read Action and Exa search Action, inspect both input schemas, and preflight them. If the estimates are within the configured limit, read openai/codex issue 37525 and search for new Codex SUBST or mapped-drive path-normalization fixes. Return the issue state, last update, human confirmation count, linked fixes, and whether any release is confirmed to contain the fix. Do not create, edit, label, close, comment on, or react to issues.

Set up Aident Loadout and monitor the Codex SUBST path bug read-only.

The measurable result is one current issue record plus a bounded list of related fixes, with no provider write. As of August 8, 2026, issue 37525 was open, had one human confirmation in addition to the original report, and did not name a released Codex version containing a fix.

Sources

• Codex issue 37525: SUBST path normalization joins physical and alias paths

• Microsoft Learn: subst command

• Node.js path.relative() documentation

• Codex issue 13846: mapped network drive path identity

• Codex fix 25509: normalize equivalent Windows paths when resuming

• Node.js issue 58989: SUBST drive-root ENOENT

Refresh this guide when issue 37525 changes state, a Codex release explicitly fixes SUBST workspace identity, or the physical-path workaround stops clearing the malformed watcher path.