Troubleshooting

Troubleshooting

Common problems and where to look. When in doubt, read the startup banner — it reports the effective config, every discovered/bridged MCP server, and every failure.

---

The connector doesn't appear / ChatGPT can't reach it

• Is the server still running? The process must stay up for connector discovery and every tool call. If you started it from the wizard's "start now" step, keep that terminal open.
• Native tunnel: does the banner say ready? It reports ready only after /readyz passes and a control-plane poll succeeds. If not, check the runtime key and tunnel ID.
• Right tunnel ID? In ChatGPT the connector must select the same tunnel ID Codex Free reports. Set Connection type: Tunnel and Authentication: None (native mode).
• External mode: is your proxy up and pointing at port 3000, with the connector URL ending in /mcp?

Tools are missing or the model won't use them

• Onboard the chat: ChatGPT Web isn't reliable about reading instructions. Open with "Call get_agent_brief and follow it for the rest of this chat." If it drifts, ask for the brief again.
• Multi-project: project-scoped tools are unavailable until you bind a project. Call set_project_root (exact path) or list_projects (by intent) first. See Multi-Project Mode.
• import_host_file gone? It's removed when artifactIngress.enabled is false.
• Large bridged tool set not surfacing? Some clients (ChatGPT included) won't show many bridged tools — use gateway mode. See Bridging MCP Servers.

A bridged MCP server didn't load

Check the banner first. The most common cause is a wrong command path:

Upstream MCP servers:
  idasql -> FAILED: could not launch 'D:/wrong/path.exe': The system cannot find the path specified.

• A failed upstream is skipped, never blocking startup or native tools.
• disabled: true shows as -> disabled.
• OAuth-only servers need a bearer token via bearerTokenEnvVar or an env-backed Authorization header — OAuth login isn't implemented.
• Legacy SSE/WebSocket transports are rejected explicitly.
• Missing plugin-provided servers? The CLI discovery step may have failed — the banner warns. Pass --codex-cli to make it mandatory, or set codexMcp.useCli.

A command was rejected

run_command only runs allowedCommands; exec_command also allows exec.extraAllowedCommands. The allowlist is checked at every command position, and command substitution ($(...), backticks) is rejected outright. Add the binary to the right list, or set exec.mode: "unrestricted" if you fully trust the caller. See Security Model.

Output looks cut off

That's intentional. Tools stop at a budget and say so on the last line:

(showing lines 1-1000 of 4820 — call again with offset=1000 for the rest)

Call again with the named argument (offset, etc.). Raise the caps in the output block if you must. See Context and Memory.

The wrong shell is running commands

The shell is picked by name from $SHELL (not the host platform). Starting from Git Bash on Windows gets bash; starting from PowerShell gets PowerShell. Override with exec.defaultShell or a per-call shell argument. Check get_environment to see what's active. See Tools Reference.

A new chat "forgot" everything

• Task state persists in ~/.codex-free/projects/<name>-<hash>/memory.json — a new chat picks it up via instructions, or one recall. If memory.enabled is false, nothing is saved.
• Multi-project bindings live in ~/.codex-free/conversation-projects/. A conversation can't switch projects — start a new chat. A stale/missing project fails closed. Delete the binding file to clear it.

Two chats are colliding on the same repo

That's what worktrees are for. In multi-project mode with mode: auto, the second chat gets its own managed worktree. If you set mode: never, they share the checkout. See Worktree Isolation.

Diagnosing anything else

Turn up logging:

codex-free -v --work-dir /path/to/project        # debug
codex-free -vv --work-dir /path/to/project       # trace
RUST_LOG=codex_free=trace,rmcp=warn codex-free --work-dir /path/to/project   # protocol level

And consider an Audit Logging to see the exact sequence of tool calls (shapes and timings, no payloads).

---

Still stuck?

• FAQ for conceptual questions.
• Open an issue with your startup banner (redact secrets) and what you expected.