Troubleshooting

If fx cannot start, sign in, or resume a conversation, run:

$fx doctor

The report checks configuration, credentials, and saved sessions, with recovery commands when available.

Diagnostic commands

Command	Description
`fx status`	Check the provider, model, and credential source.
`fx permissions --json`	List active permission rules.
`fx workspace --json`	List accessible directories.
`fx models --json`	List available models.
`/trace`	Create a private diagnostic trace.

`fx: command not found`

Open a new terminal to pick up the installer's PATH change. If fx is still missing, add its default install directory:

$export PATH="$HOME/.local/bin:$PATH"

If you chose a different FX_INSTALL_DIR, use that path instead of ~/.local/bin.

Run fx status to check the provider and credential source, then reconnect:

Provider	Command
ChatGPT	`fx login codex`
Grok	`fx login grok`
Vercel	`fx login vercel`

To change providers, use /provider in fx. Environment credentials can take precedence over saved logins; check Credential selection if reconnecting does not change the account.

If the browser does not open, use the authorization URL printed by the login command.

fx cannot reach AI Gateway

fx needs access to Vercel AI Gateway means the selected Gateway credential is unavailable. Run fx login vercel to sign in, fx setup to save an API key, or set AI_GATEWAY_API_KEY.

For stored-key errors:

fx could not read the stored API key: save the key again with fx setup, or select another credential source in /provider.
fx setup reports that stored API keys are disabled: unset FX_DISABLE_KEYCHAIN and retry, or use AI_GATEWAY_API_KEY.

To use a different provider, follow Authentication.

A custom model connection fails

Run fx status --json and check provider_endpoint and the selected model.

Connection definitions belong under top-level providers in ~/.fx/settings.json, not project .fx.json. Check the API prefix, the exact served model ID, and the environment variable named by auth.env. fx setup does not save a custom-provider key, and fx does not fall back to a Gateway key for that connection.

If text works but tools fail, check the model's function-tool support and the server's tool-call parser. A rejected resume can mean that the saved endpoint or credential slot changed. See custom connection troubleshooting for these cases and the adapter's limits.

The model is not the one I chose

Check the model and account with /status. The --model flag and FX_MODEL override the choice saved in your profile; remove them if you want the picker selection to apply.

Also check workspace overrides in ~/.fx/settings.json. See Model selection order.

A model is missing from the catalog

Run fx models to see the current catalog and fx status to check the provider and account. Use /provider to change them.

With a Vercel login, the selected team also affects the catalog. Run fx teams to choose it; /status shows gateway_team.

fx stops before running a tool

Open /permissions to check the mode and rules. A deny rule blocks the matching action.

In auto mode, a review may hold an action and return guidance to the agent. To use approval prompts, switch to /permissions ask.

For fx ask --json or --quiet, add --prompt-permissions and run from a terminal to answer approvals. With piped input, configure a rule for the action or run it interactively. See Permissions.

fx ignores my AGENTS.md

Check these settings and locations:

context: false in .fx.json or your profile disables project instructions.
A nested AGENTS.md can override instructions from its parent directory.
An additional workspace does not contribute project instructions.
Files that exceed the per-file or combined context limit may be truncated or omitted. Shorten the file or increase the relevant limit.

A session will not open or resume

fx doctor reports session damage and suggests recovery commands. To recover readable history into a separate session, preserving the original:

$fx session recover <session-id>

To inspect one session without starting a turn:

$fx session --id <session-id> --json

fx automatically retries transient provider and network failures. If fx exits unexpectedly during recovery, reopen the conversation and send continue to retry. For a noninteractive run, use fx ask --resume last --continue-recovery. See Sessions.

An MCP server is missing

$fx mcp list

This lists configured servers. Add --connect to try connecting and see their health, or use /mcp inside fx.

What you see	What to check
A project server is pending	Approve it with `/mcp trust approve <name>`.
A configuration warning names an environment variable	Set that variable before starting fx, or provide a default in the project config.
A server times out during startup	Check its command or URL. If startup normally takes over 30 seconds, increase `startup_timeout_ms`.
A manual config edit has not taken effect	Run `/mcp reload`. Invalid configuration or a failed required server leaves the previous configuration running.
The wrong server appears under a name	Profile entries take precedence over same-name project entries.
A profile server is missing in an editor	ACP uses client-supplied and approved project servers, not `~/.fx/mcp.json`.

See MCP for setup and configuration.

A skill is missing

Open /skills and check:

The skill is in a supported discovery location.
Its SKILL.md has valid frontmatter. Startup warnings identify unreadable or malformed skills.
It is in the primary project or a user skill directory. Additional workspaces do not contribute skills.

An embedded agent cannot load

Check the Node SDK's backend diagnostic. It distinguishes a missing native addon from a WebAssembly runtime without JSPI. The embedded agent needs explicit credentials and tools; it does not load your fx CLI profile.

The terminal renders incorrectly

Try disabling synchronized terminal updates:

$FX_SYNC_UPDATES=off fx

If the problem persists, capture it so it can be reproduced:

$FX_RECORD=./repro.fxtape fx

After reproducing the issue, exit fx and replay the recording:

$fx replay ./repro.fxtape

See Share feedback for attaching the recording to a report.

Costs are higher than expected

fx usage reports only what fx recorded on this machine. Auto reviews, context compaction, vision fallback, and session titles can add model requests. Title requests are excluded from session usage totals. Web search can also add costs. See Usage and costs.

For a problem not covered here, report it with the steps to reproduce it.