VS Code extension WSL agent fails when Windows and WSL share CODEX_HOME on C drive SQLite state

[4everWZ]

What version of the IDE extension are you using?

26.519.32039

What subscription do you have?

Plus

Which IDE are you using?

VS Code

What platform is your computer?

Windows x64 with WSL2 Ubuntu-24.04

What issue are you seeing?

When the VS Code Codex extension is configured with:

Agent environment: Windows Subsystem for Linux

the extension launches the WSL Codex app-server through wsl.exe and tries to initialize SQLite state under the shared WSL CODEX_HOME:

/home/lawrence/.codex

Because this path is a symlink to the Windows C-drive Codex home:

/mnt/c/Users/Artoria/.codex

the WSL Linux Codex binary and Windows Codex binary end up sharing the same SQLite state databases on:

/mnt/c

This causes the WSL app-server to fail with errors like:

Error: failed to initialize sqlite state runtime under /home/lawrence/.codex:
failed to initialize state runtime at /home/lawrence/.codex:
error returned from database: (code: 4618) disk I/O error

or:

Error: failed to initialize sqlite state runtime under /home/lawrence/.codex:
failed to initialize state runtime at /home/lawrence/.codex:
migration 1 was previously applied but has been modified

In VS Code extension logs, the WSL launch command looked like:

wsl.exe -d Ubuntu-24.04 -- /usr/bin/bash -lc /usr/bin/env \
'PATH=/mnt/c/Users/Artoria/.vscode/extensions/openai.chatgpt-26.519.32039-win32-x64/bin/linux-x86_64:$PATH' \
RUST_LOG=warn \
CODEX_INTERNAL_ORIGINATOR_OVERRIDE=codex_vscode \
/mnt/c/Users/Artoria/.vscode/extensions/openai.chatgpt-26.519.32039-win32-x64/bin/linux-x86_64/codex \
app-server --analytics-default-enabled

Windows native mode still works:

codex doctor --summary

13 ok · 1 idle · 1 notes · 0 warn · 0 fail ok

But WSL mode fails unless CODEX_SQLITE_HOME is set to a WSL-native directory.

What steps can reproduce the bug?

1. On Windows, use the VS Code Codex extension.

2. Use a shared Codex home between Windows and WSL:

   C:\Users\Artoria\.codex
   /home/lawrence/.codex -> /mnt/c/Users/Artoria/.codex
   

3. Open Codex extension settings.

4. Set:

   Agent environment: Windows Subsystem for Linux
   

5. Let VS Code reload.

6. Open the Codex sidebar / start the extension.

7. The WSL app-server fails during SQLite state runtime initialization.

The same failure can be reproduced from WSL without the workaround:

wsl.exe --distribution Ubuntu-24.04 -- /usr/bin/bash -lc \
'/mnt/c/Users/Artoria/.vscode/extensions/openai.chatgpt-26.519.32039-win32-x64/bin/linux-x86_64/codex doctor --summary'

It reports:

state database integrity check failed

What is the expected behavior?

The VS Code extension should support Windows + WSL usage without both platforms fighting over the same SQLite files on /mnt/c.

Expected behavior would be one of:

1. The extension automatically sets a WSL-local CODEX_SQLITE_HOME when launching WSL agent mode.
2. The extension exposes a setting for WSL CODEX_SQLITE_HOME.
3. Codex automatically avoids storing SQLite state under /mnt/c/.../.codex when running inside WSL.
4. Documentation explains the recommended Windows + WSL split-state setup.

A working layout is:

Windows:
  CODEX_HOME = C:\Users\Artoria\.codex

WSL:
  CODEX_HOME = /home/lawrence/.codex -> /mnt/c/Users/Artoria/.codex
  CODEX_SQLITE_HOME = /home/lawrence/.codex-sqlite

This preserves shared auth/config/sessions while keeping SQLite state platform-local.

Additional information

Current workaround:

Create:

/home/lawrence/.codex-wsl-env

with:

export CODEX_SQLITE_HOME="$HOME/.codex-sqlite"

For VS Code Windows extension WSL agent mode, source it from:

/home/lawrence/.profile

[ -f "$HOME/.codex-wsl-env" ] && . "$HOME/.codex-wsl-env"

For VS Code Remote-WSL mode, source it from:

/home/lawrence/.vscode-server/server-env-setup

[ -f "$HOME/.codex-wsl-env" ] && . "$HOME/.codex-wsl-env"

After applying this workaround, the WSL Linux Codex binary passes state initialization:

codex doctor --summary

11 ok · 1 idle · 3 notes · 2 warn · 0 fail degraded

The remaining warnings are terminal/search-related, not SQLite state failures.

Important detail: putting this only in .bashrc is not reliable for the VS Code extension WSL agent mode, because the extension launches WSL through non-interactive bash -lc. In my setup, .bashrc intentionally returns early for non-interactive shells.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Codex Desktop WSL mode reuses Windows CODEX_HOME and fails SQLite migration checksum #23913
• Bug: Codex Desktop fails after enabling WSL #23927
• WSL CLI cannot share Windows Codex App CODEX_HOME: migration 1 was previously applied but has been modified #23251
• Codex Windows Store 26.519.2736.0 fails on startup: "migration 1 was previously applied but has been modified" #23923

Powered by Codex Action

[4everWZ]

There are two affected VS Code + WSL usage modes:

1. Windows VS Code + Codex extension with Agent environment: Windows Subsystem for Linux

   In this mode, the Windows VS Code extension launches the Linux Codex binary through wsl.exe.

   For this path, setting CODEX_SQLITE_HOME in .bashrc is not reliable because the extension launches WSL through a non-interactive bash -lc command. In my setup, sourcing the workaround from ~/.profile works.

2. VS Code Remote-WSL + Codex extension opened inside WSL

   In this mode, the extension runs through the VS Code server inside WSL.

   For this path, sourcing the same workaround from:

   ~/.vscode-server/server-env-setup

[yui-stingray]

I checked current main (9f42c89) against the WSL split-state workaround described here. The code path appears to support this as an intended configuration path, not just an accidental workaround:

• codex-rs/core/src/config/mod.rs:3224-3229 resolves sqlite_home from explicit sqlite_home, then CODEX_SQLITE_HOME, and only then falls back to CODEX_HOME.
• codex-rs/state/src/lib.rs:72-77 defines the CODEX_SQLITE_HOME override and the runtime SQLite DB filenames.
• codex-rs/app-server/src/lib.rs:531-537 fails app-server startup when rollout_state_db::try_init(&config) cannot initialize SQLite under the resolved sqlite_home, which matches the failure shape in this report.
• codex-rs/cli/src/doctor.rs:1049-1059 and :2083-2091 expose/check the resolved sqlite home, so codex doctor --summary / codex doctor --json should be useful when run from the same WSL launch environment being diagnosed.

I also did not find user-facing docs for the Windows + WSL split-state layout beyond the config schema entry for sqlite_home (codex-rs/core/config.schema.json:4923-4929). The likely low-risk follow-ups seem to be either documenting the WSL launch-env requirement, or having the VS Code WSL launcher set/pass a WSL-local SQLite home before app-server startup when it detects a shared /mnt/<drive>/.../.codex home.