Troubleshooting for beginners

Back to the Codex learning hub

Goal and how to use this guide

The diagram maps 01 to recording symptoms, 02 to one minimal check and 03 to repeating the original action after correcting the cause. Do not retry immediately on every error: retain input, state and the working environment before narrowing the problem.

First: Record the symptom and last successful action

Record time, platform, app/CLI version, current folder, exact command/action, expected result and original error. Share relevant details with accounts, private paths and credentials redacted. Preserve installation output if a command is missing afterward, or task/host identity if another run is active. Do not crop an error to red text alone: the preceding command and working directory often determine the next step.

# Troubleshooting record
- Time and timezone:
- Surface: desktop / CLI / IDE / mobile / web
- OS and app or CLI version:
- Working folder or execution host (redacted if shared):
- Exact command or UI action:
- Expected result:
- Actual error and exit status:
- Last successful action:
- One change attempted:
- Result after that change:
- Files or settings to restore:

Installation, login and platform surfaces

codex not found: CLI setup

PowerShell blocks a script: Windows CLI

Different macOS/Linux install paths: macOS · Linux/WSL

Unauthorized after login: Account/usage

Missing desktop/mobile control: Platform selection

Windows, WSL, containers and remote hosts need not share login/configuration even on one computer. Identify the failing environment.

Use Get-Command codex on Windows or command -v codex on macOS/Linux to locate the executable. Record multiple installations before deleting versions or changing machine-wide security policy. Distinguish ChatGPT authentication, API keys and organization restrictions; reinstalling does not replenish quota. For possible service incidents, compare the official status page with your timestamp and affected service. Overall service health does not prove your network and permissions work.

Folders, MD files and configuration

Edits do not appear: Paths · Browser

AGENTS.md seems ignored: Rule scopes

README treated as permanent rules: Document roles

config.toml parse failure: Config troubleshooting

Resume repeats stale conclusions: Sessions · Handoff

Change one condition at a time. After recovery, keep necessary changes and remove your diagnostic markers rather than replacing the full config with an online template.

Reproducible drill: find the correct folder

Create a new path-trouble folder with empty project and other subfolders. Put marker.md only in project with the line below. Open a terminal in other and deliberately try reading marker.md to reproduce a missing file without Codex or production changes. Inspect the current directory and file list, read the marker through an explicit relative path, then cd into project and repeat the original read command.

# Correct folder: PATH-PRACTICE-1

Get-Content -LiteralPath .\marker.md
Get-Location
Get-ChildItem
Get-Content -LiteralPath ..\project\marker.md
Set-Location -LiteralPath ..\project
Get-Content -LiteralPath .\marker.md

cat ./marker.md
pwd
ls
cat ../project/marker.md
cd ../project
cat ./marker.md

The first read fails; the next two show the same PATH-PRACTICE-1. You corrected location, not file contents. Return to your original working folder afterward and retain the fixture without recursive deletion. In Codex, first ask for its working root and whether a specified file exists before deciding that the wrong project is open. Same-named desktop tasks, another worktree or old phone content are not proof of the same folder.

For Get-Content, a PowerShell cmdlet, save $? immediately; $LASTEXITCODE is primarily for native programs such as codex or node. After the path exercise you should be in project. The blocks below read missing other/marker.md, then the real marker. Expect False then True in PowerShell, or nonzero then 0 in the shell. Do not wait until other commands replace the status.

Get-Content -LiteralPath ..\other\marker.md
$practiceReadOk = $?
$practiceReadOk
Get-Content -LiteralPath .\marker.md
$practiceReadOk = $?
$practiceReadOk

cat ../other/marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"
cat ./marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"

See PowerShell's automatic variables for exact definitions. Neither read changes the marker. Investigate unexpected edits separately, so the handoff distinguishes corrected paths from preserved file contents.

Tools, remote work and automation

Skill visible but behaves wrongly: Skill acceptance

Installed plugin cannot read data: Plugin troubleshooting

MCP configured but tools unavailable: MCP troubleshooting

Phone shows stale data: Remote setup · Cross-device

Agent reports done but results conflict: Agent quality · Integration

Schedule times out or duplicates: Automation recovery

JSON answer despite failed process: JSON/JSONL

Address the relevant layer: plugin installation and source-account access are distinct states.

Close the incident and resume work

Repeat the originally failing action after fixing it, then test a nearby behavior: check Active after fixing Completed, preserve earlier working configuration after a config edit, or actually read a fictional document after reconnecting MCP rather than trusting a green icon. Record symptom, cause, one correction and verification in issue-notes.md. For handoff, provide minimal input and attempted steps. If unresolved, say so and preserve a usable state plus the next evidence to collect.

Remove your temporary markers/settings while keeping the necessary fix, backups and records. Troubleshooting is not a reason to clear all configuration, delete sessions or expose sensitive content. You do not need to execute this index from top to bottom: choose the row matching your symptom. Return to the Learning hub from the top/bottom of any lesson and search a feature, command or MD filename. Record unavailable platform features separately from installation failures.

Back to the Codex learning hub

Read the full description

Symptom to One check to Retry

• AI tools
• Tutorials
• Codex