Troubleshooting

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

$fx doctor

fx doctor checks that fx can work in the current folder. It reads your settings, environment values, MCP configuration, skills, saved sessions, and git repository, then checks over the network that:

  • The provider accepts your credential and lists your model. fx asks AI Gateway, ChatGPT, or Grok for its model list and makes no model call. A provider configured under providers in your settings is not asked.
  • Each approved MCP server starts and lists its tools. Each server is checked in its own fx mcp show process. Checks run in the order of your configuration, at most one per CPU at once, at least 4 and at most 16, and the next starts as one ends. So servers that hang hold their places until the limit, and servers queued behind them are reported as not checked. An unapproved project server is never started.
  • The GitHub CLI can use the repository, when the folder is in a git repository. fx doctor runs gh repo view there, so gh picks the remote, host, and account, and reads GH_HOST and GH_REPO, as it does for fx pr --create and fx issue --create, which need it. A gh that needs a sign-in gets the fix gh auth login. For any other problem, run gh repo view to see what gh says.

The network checks share one 5 second limit. A provider or MCP server that does not answer in time fails with its own line, which for a server says how long its check ran, and so does a server whose check had not started. A check starts only while enough of the limit is left for it to answer. A gh that does not answer only warns, since gh is optional.

While the network checks run, fx doctor checks your 64 most recent saved sessions within the same limit. It reads each session's log and checks that every file the log names is there. Sessions it could not check to the end before the limit are counted in the report. To also read every saved file and check its contents, with no time limit, run fx doctor --deep. On a profile with large sessions this can take minutes.

$fx doctor --deep

In a terminal, fx doctor says on stderr what it is checking and clears those lines before its report. Ctrl-C stops fx doctor together with every check it started, MCP servers included. If fx doctor itself is killed with kill -9, its checks run until their own timeouts end.

The report starts with the workspace, model, credential, and permission mode fx doctor ran with. Then it lists each check under its group, such as Config, Sessions, or MCP servers, marked ✓ when it is ok, ! for a warning, or ✗ for a failure, and ends with the totals. In a terminal the marks are in color, unless NO_COLOR is set, and a long line wraps under its own column. Every problem has a fix: line under it with the command or change that solves it. A server name from a configuration file is quoted, so the line is safe to paste into a shell. For a server whose name starts with -, the fix is always to rename it in the file it comes from, whatever else is wrong with it, since fx mcp commands read such a name as an option. fx doctor exits with status 0 when no check fails, 1 when one fails, and 2 for a flag it doesn't know. Add --json for the same report as JSON, with a status of ok, warn, or fail and a fix on each check.

fx doctor changes nothing. Old terminal and side folders whose session is gone are counted, and fx doctor --fix removes them.

$fx doctor --fix

Diagnostic commands

CommandDescription
fx statusCheck the provider, model, and credential source.
fx permissions --jsonList active permission rules.
fx workspace --jsonList accessible directories.
fx models --jsonList available models.
fx config list --show-originList the values in each settings file and where each one is set.
/traceCreate 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.

Sign-in is missing or expired

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

ProviderCommand
ChatGPTfx login codex
Grokfx login grok
Vercelfx 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.

If your sign-in expires while fx is responding, fx opens sign-in for you and continues the request once you finish. See fx asks you to act during a response.

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 login vercel --api-key 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 login vercel --api-key, or select another credential source in /provider. To see which step failed, turn on a debug log and retry.
  • fx login 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.

fx asks you to act during a response

When a request can't continue without you, fx pauses it and the status line says what it needs. Press escape at any of these to end the request.

Status lineWhat to do
Sign-in expired · waiting 1m 05s · next try in 1m 55sFinish signing in in the sign-in fx opens. The request continues on its own, with the team you choose there. While it waits, fx tries your current login again every 3 minutes, so a login that works again also continues it. If the sign-in code expires, press enter to retry with your current login, or run /login to sign in again.
Out of creditsChoose I added credits, retry, Switch to another model, or Cancel this turn. Switching puts your message back in the composer.
Blocked by the content filter · press Esc and rephrasePress escape, then rephrase your message.
The provider rejected this request · press EscPress escape, then change the request.
Still too long after compacting · press Esc and shorten your messagePress escape, then shorten your message.
This request crashed fx twice · Enter to retry, Esc to cancelPress enter to send the request again.
Interrupted more than a day ago · Enter to resume, Esc to cancelPress enter to send the request again.

When AI Gateway refuses a login that fx has just refreshed, the login itself still works, so fx doesn't ask you to sign in again. It shows the gateway's reason once with the Vercel team it sent the request for, the status line reads Gateway refused the login · next try in 8s · attempt 3, and fx retries with the same login until the gateway accepts it. Each retry refreshes the login again, and if that refresh fails, fx asks you to sign in. Press escape twice to stop it, as for any retry. If the gateway refuses the login because the team is wrong, stop the request, run /login, choose another team, and send your message again.

fx ask and ACP clients don't wait: fx ends the request with a message instead. fx ask exits with status 1; see Retries and requests that need you.

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 login vercel --api-key saves only an AI Gateway key, not 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. If resuming a session says its custom connection changed or is no longer in ~/.fx/settings.json, change the connection's protocol, base_url, or auth back, or start a new session. See custom connection troubleshooting for these cases and the adapter's limits.

A local model that loads on its first request can take longer than fx waits for a response to start; raise timeouts.first_response_ms. If fx models says it is showing the models in settings, the server's model list request failed, and the same line says why. If fx says an effort is not available for a model, add that level to the model's reasoning_efforts.

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; fx config list --show-origin shows which file sets each value. 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; the Team line of /status shows it.

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.

A reply runs out of output tokens

A model can use its whole output limit before it answers, for example by reasoning for a long time or by writing a very large tool call. fx never runs a tool call that the limit cut off.

When the reply ran out before any text, fx drops it and sends the request once more if it can change the request. It asks for low effort when the model offers low and you selected a higher effort or the default, and it sends a higher output limit when the first request named none and the provider accepts one. fx prints what it changed, such as The reply ran out of output tokens before any text. Retrying with low effort. The next request uses your selected effort again.

The turn ends when the reply already showed text, when the second reply also runs out, or when fx can't change the request. If a cut-off tool call ends the turn, fx says The reply ran out of output tokens before its tool calls were complete, so I did not run them. Send your message again, or ask for a smaller step, such as writing a large file in parts.

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 retries provider and network failures until the request goes through. Press escape twice to stop. If fx exits during a response, the next fx you start in that workspace shows Interrupted turn · /resume to continue. Reopen the session with /resume or fx -c, and fx sends the interrupted request again on its own. For a noninteractive run, use fx ask --resume last "continue". See Sessions.

An MCP server is missing

$fx mcp list

This lists configured servers and their status without connecting. Run fx mcp show <name> to connect to one and see why it isn't ready, or open /mcp inside fx. The status line also names a server that needs you.

What you seeWhat to check
A project server is waiting for approvalApprove it with /mcp approve <name>.
A server needs loginSign in with /mcp login <name>.
A server refused the loginfx mcp show <name> and the status line say <name> refused the saved login, with the server's own error when it gave one. The server's words are in quotes, as in <name> refused the saved login (invalid_token: "No authorization provided"). Sign in again with /mcp login <name>. If that says <name> refused the new login, the server turned down the token it just issued, and nothing is saved. Try again, and if it keeps refusing, check the server's setup or contact whoever runs it.
Signed in to <name>, but fx couldn't check the login with itThe login is saved, but fx couldn't tell whether the server takes it: the server gave no answer, or answered with an error that wasn't about the login. Run fx mcp show <name> once the server is reachable.
A server needs an environment variableSet that variable before starting fx, or provide a default with ${VAR:-default}.
A local server stops as soon as it startsLocal servers get only HOME, LOGNAME, PATH, SHELL, TERM, and USER from fx. Add any other variable the command needs to the server's env.
A server is not supportedfx doesn't connect to legacy HTTP+SSE servers. Use the server's Streamable HTTP URL.
A server failedRun fx mcp show <name> to see its error, then check its command or URL.
A server failed because its saved logins couldn't be readfx mcp show <name> names the file or Keychain item. A newer fx may have saved it, or it's damaged: fix or delete it. If the Keychain was only slow, run fx mcp show <name> again.
A manual config edit has not taken effectRun /mcp list. fx loads a changed mcp.json or .mcp.json when you send your next prompt or run a /mcp command.
The wrong server appears under a nameProfile entries take precedence over same-name project entries.
A profile server is missing in an editorACP uses client-supplied and approved project servers. Profile servers need the client to opt in.

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. Full detail, which ctrl+o opens, lists skills fx couldn't read or parse.
  • If the skill folder is a symbolic link, its target is in a place fx loads links from.
  • 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 shows what your provider reports for the account, including other devices and applications, and the latest requests can take a few minutes to appear. Auto reviews, subagents, context compaction, vision fallback, session titles, cache warming, and resent replies can add model requests. Web search can also add costs. See Additional model requests.

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