Troubleshooting Codex in VS Code: common errors and fixes

When Codex fails in VS Code, do not begin by deleting configuration, credentials, or editor state. First identify which layer is broken:

1. extension and sidebar;
2. repository context and trust;
3. authentication;
4. configuration precedence;
5. approval and sandbox policy;
6. MCP server;
7. local runtime.

This order preserves evidence and avoids turning one problem into three.

Quick diagnostic checklist

Run these before a broad reset:

codex login status
codex mcp list --json
codex doctor

Then record:

• the exact error text;
• whether the CLI works in the same repository;
• whether a new editor session changes the result;
• which config.toml files apply;
• whether the project is trusted;
• whether the failure affects base Codex or only one MCP server.

The current developer command reference documents all three commands.

The Codex sidebar is missing

Symptom

The extension appears installed, but no Codex panel is visible.

Fix

1. Confirm the official Codex extension is installed and enabled.
2. Open the Command Palette.
3. Run:

Codex: Open Codex Sidebar

4. If VS Code asks for a reload after installation or update, reload the editor.

Use the current Codex IDE quickstart instead of downloading an unofficial package.

Codex opened the wrong project

Symptom

Codex cannot find files, ignores AGENTS.md, shows unrelated Git changes, or proposes paths outside the expected package.

Fix

Check the workspace root in VS Code and the repository path in the integrated terminal:

git rev-parse --show-toplevel
git status --short --branch

If the repository is a monorepo, open the root that contains the intended .codex and AGENTS.md files. A nested folder can legitimately receive different project configuration.

Project config is ignored

Symptom

Edits to .codex/config.toml have no effect.

Fix

First confirm the project is trusted. Codex skips project-scoped .codex layers for untrusted projects.

Then check the current configuration precedence:

1. CLI flags and --config
2. trusted project config, closest file first
3. selected profile
4. user config
5. system config
6. built-in defaults

A launch override or a config file closer to the current directory can correctly win over the file you edited.

Sign-in or authentication fails

Symptom

The extension asks you to sign in repeatedly or cannot start an authenticated task.

Diagnose

From the same machine:

codex login status

The command reports the active authentication mode and exits successfully when credentials are present.

If the status is not valid, use an available official login flow:

codex login

For environments where a browser cannot open:

codex login --device-auth

Do not paste credentials into a project file or command argument. The command reference supports reading an API key or access token from standard input when that authentication method is required.

Codex asks for unexpected approvals

Symptom

Every command prompts, or Codex cannot write files you expected it to change.

Diagnose

Approval and sandboxing are independent:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

The approval policy decides when Codex can ask. The sandbox decides what command execution can access.

Check the active session rather than only the user config. A project file, profile, or launch flag may override it.

Do not solve repeated prompts by jumping to danger-full-access. First determine which exact action falls outside the workspace boundary.

See the Codex approvals and sandbox guide for current values and safe combinations.

MCP tools are missing or time out

Symptom

Codex itself works, but one external tool is absent, fails to start, or cannot authenticate.

Diagnose configuration

codex mcp list --json
codex mcp get server-name --json

If the server does not appear, debug its config location, syntax, trust, and precedence.

Diagnose transport

For a local STDIO server, run the configured command in the same environment and confirm the executable exists.

For a Streamable HTTP server, verify the URL and authentication separately. An authorization error proves the server was reachable; it does not prove the token was accepted.

For an OAuth-capable remote server:

codex mcp login server-name

The Codex MCP configuration guide covers the current transports and command surface.

Commands work in a terminal but not in the extension

Symptom

An MCP launcher, formatter, package manager, or script works in your interactive shell but fails when Codex launches it.

Fix

Compare the environments without printing secret values:

command -v node
command -v pnpm
command -v codex

Prefer stable executables available on the normal PATH. Do not depend on a shell alias or a variable initialized only by one interactive shell startup file.

If necessary, configure the shell environment policy deliberately. Avoid forwarding every secret-bearing environment variable to generated commands.

The extension becomes slow or unresponsive

Isolate the scope

1. Start a fresh Codex chat in the same repository.
2. Disable or remove an obviously failing MCP entry.
3. Try a small read-only prompt.
4. Check whether the repository contains very large generated or vendor directories.
5. Run codex doctor.

If only one server causes the delay, fix the server instead of resetting Codex. If only one project causes it, inspect project instructions, hooks, config, and repository size.

Git shows files Codex did not edit

The editor shows repository changes, not proof of authorship. Check:

git status --short
git diff --name-only
git diff --staged --name-only

Preserve existing user changes. Review the last turn separately when the interface provides that view.

Run the full diagnostic report

The current CLI includes:

codex doctor

It covers installation, configuration, authentication, runtime, Git, terminal, app-server, and thread inventory. Run it before reinstalling when the failure crosses several layers.

Keep the report private if it includes local paths or environment details.

When a reinstall is appropriate

Reinstall or update only after:

• the extension cannot load at all;
• the official install path is confirmed;
• authentication and config have been checked independently;
• codex doctor points to installation/runtime damage;
• a fresh editor session does not help.

A reinstall cannot fix a bad project config, missing project trust, broken MCP server, or wrong repository root.

A useful support report

If the issue persists, collect:

• product surface and version;
• operating system and editor version;
• exact error text;
• minimal reproduction;
• whether the CLI works;
• codex login status result without credentials;
• relevant codex doctor section with private details removed;
• whether all MCP servers were disabled for the test.

This is far more actionable than “Codex stopped working.”

Related guides

• Install Codex in VS Code
• Use Codex CLI and VS Code together
• Configure approvals and sandboxing

The reliable troubleshooting habit is simple: prove the failing layer, preserve evidence, and change one variable at a time.