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 Codexify 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.
• No repository needed: choose Chat without a project in the setup app, or call set_project_root with withoutProject: true, to get a private scratch workspace. This choice cannot later be changed into a project binding in the same chat.
• import_host_file gone? It's removed when artifactIngress.enabled is false.
• No setup/diff/updater cards? uiWidgets: false deliberately removes Codexify's built-in MCP Apps and their widget metadata. The underlying tools remain available.
• 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 ~/.codexify/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 ~/.codexify/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.

The background service or self-update failed

Start with the rotating service log:

codexify service logs
codexify service logs -f

• codexify service enable starts an installed service; service install recreates/updates its definition from the selected config.
• self_update accepts only the standard ~/.codexify/bin installation and requires confirm=true after an explicit update request.
• A service-supervised successful update intentionally disconnects MCP while the detached worker swaps the executable and restarts the service.
• After the updated server restarts, open ChatGPT Settings, select the Codexify connector, scroll to the bottom of its tool list, and click Refresh so ChatGPT reloads the updated connector schema.
• With uiWidgets: false, self_update does not emit the updater component or component-only changelog payload; follow progress with codexify service logs -f.
• Windows self-update requires the background service; use the release installer first if Codexify was installed another way.
• A fixed update lock rejects overlapping updates. If an earlier updater really is no longer running, the log identifies the stale lock path and remediation.

The setup app reports warnings or stale tools

• Check for updates performs a fresh release check instead of reusing the normal latest-version cache.
• Doctor runs structured diagnostics asynchronously. Healthy automatic results stay hidden; warnings are summarized, failures expand into individual checks, and Autofix sends the findings to ChatGPT for remediation.
• If setup says the connector schema is stale, use its row-local Refresh action. The app accepts a connector slug only from a same-origin asdk_app_<slug>.web-sandbox.oaiusercontent.com ancestor, then opens the relative #settings/Plugins/plugin_asdk_app_<slug>:~:text=Information-,Refresh,-Connected route through ChatGPT's link-opening API; if that sandbox identity is unavailable it falls back to #settings/Plugins. The app does not send a Refresh prompt to the model or mutate connector state. In Settings, select Codexify if necessary, scroll below the tool list, and click the host-side Refresh control.

Diagnosing anything else

Turn up logging:

codexify -v --work-dir /path/to/project        # debug
codexify -vv --work-dir /path/to/project       # trace
RUST_LOG=codexify=trace,rmcp=warn codexify --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.