Troubleshooting
If fx cannot start, sign in, or resume a conversation, run:
fx doctorfx 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
providersin your settings is not asked. - Each approved MCP server starts and lists its tools. Each server is checked in its own
fx mcp showprocess. 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 doctorrunsgh repo viewthere, soghpicks the remote, host, and account, and readsGH_HOSTandGH_REPO, as it does forfx pr --createandfx issue --create, which need it. Aghthat needs a sign-in gets the fixgh auth login. For any other problem, rungh repo viewto see whatghsays.
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 --deepIn 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 --fixDiagnostic 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. |
fx config list --show-origin | List the values in each settings file and where each one is set. |
/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.
Sign-in is missing or expired
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.
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 withfx login vercel --api-key, or select another credential source in/provider. To see which step failed, turn on a debug log and retry.fx loginreports that stored API keys are disabled: unsetFX_DISABLE_KEYCHAINand retry, or useAI_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 line | What to do |
|---|---|
Sign-in expired · waiting 1m 05s · next try in 1m 55s | Finish 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 credits | Choose 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 rephrase | Press escape, then rephrase your message. |
The provider rejected this request · press Esc | Press escape, then change the request. |
Still too long after compacting · press Esc and shorten your message | Press escape, then shorten your message. |
This request crashed fx twice · Enter to retry, Esc to cancel | Press enter to send the request again. |
Interrupted more than a day ago · Enter to resume, Esc to cancel | Press 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: falsein.fx.jsonor your profile disables project instructions.- A nested
AGENTS.mdcan 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> --jsonfx 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 listThis 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 see | What to check |
|---|---|
| A project server is waiting for approval | Approve it with /mcp approve <name>. |
| A server needs login | Sign in with /mcp login <name>. |
| A server refused the login | fx 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 it | The 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 variable | Set that variable before starting fx, or provide a default with ${VAR:-default}. |
| A local server stops as soon as it starts | Local 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 supported | fx doesn't connect to legacy HTTP+SSE servers. Use the server's Streamable HTTP URL. |
| A server failed | Run fx mcp show <name> to see its error, then check its command or URL. |
| A server failed because its saved logins couldn't be read | fx 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 effect | Run /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 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. 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.mdhas valid frontmatter. Full detail, whichctrl+oopens, 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 fxIf the problem persists, capture it so it can be reproduced:
FX_RECORD=./repro.fxtape fxAfter reproducing the issue, exit fx and replay the recording:
fx replay ./repro.fxtapeSee 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.