Troubleshooting

Start here when fx does not behave the way the rest of these docs describe. Most answers come from one command:

fx doctor checks the workspace, configuration, authentication, resolved startup settings, local session state, and Git integrations without starting an agent turn. When fx can recover a session problem, the output includes the exact command to run.

Diagnostic commands

fx: command not found

The installer places the binary in ~/.local/bin, or in FX_INSTALL_DIR when you set it. If that directory is not on your PATH, the installer appends a PATH line to your shell profile, which takes effect in new shells.

Add it to the current shell:

See Installation for the full list of what the installer changes.

fx cannot reach AI Gateway

Fx needs access to Vercel AI Gateway. means no usable credential was found. Sign in, save an API key, or provide one for the process:

fx uses the first available credential: VERCEL_OIDC_TOKEN, then AI_GATEWAY_API_KEY, then a saved fx login session, then a key saved with fx setup. A source chosen in /setup wins until it becomes unavailable. See Credential selection.

A few specific cases:

• The browser never opens. On a headless machine or over SSH, set FX_NO_OPEN_BROWSER=1 before fx login to print the authorization URL instead.
• Fx could not read the stored API key. A key may be saved but unreadable. Set FX_TRACE_LOG to capture the failing step, or set AI_GATEWAY_API_KEY for the run.
• fx setup refuses to save a key. FX_DISABLE_KEYCHAIN=1 disables the native macOS key store, and fx setup cannot save a key while it is set.
• The session expired. fx doctor reports the auth check as a warning. fx login refreshes it.

The model is not the one I chose

fx status and /status print the effective model. fx resolves it in this order: FX_MODEL for the process, a legacy workspace override if one still exists, your user default in ~/.fx/settings.json, then the compiled default. Project .fx.json cannot set model, so a repository never changes your selection. See Models.

A model is missing from the catalog

The catalog depends on the active credential and the selected Vercel team, so availability can differ between teams. /status prints the active gateway_team.

Before authentication the catalog shows only public models. fx teams requires an fx login session.

fx stops before running a tool

In auto mode, saved rules are applied first, unresolved sensitive calls are reviewed automatically, and an unresolved result falls back to a human prompt in the interactive shell.

fx ask cannot pause for approval, so an unresolved call ends the run before the tool executes. Options, from narrowest to broadest:

1. Add an allow rule for the exact action with /allowlist.
2. Pass --auto so unresolved requests are reviewed automatically.
3. Pass --yolo only in an environment you are willing to lose; it disables fx permission checks and command sandboxing for that run.

An interrupted headless run exits with code 130. See Permissions and fx ask.

An approved command still cannot do something

Permissions decide whether a command may run; the sandbox limits what it can do once it starts. On macOS the os sandbox restricts writes to the primary workspace, active additional directories, temporary paths, and required device paths. Approving a command is a separate decision from widening the sandbox, so interactive fx may ask again for the broader access.

Inspect or change the sandbox with /sandbox, and confirm reachable directories with fx workspace --json. Adding a directory grants tool access, not permission; see Additional workspaces.

fx ignores my AGENTS.md

• Only the primary workspace contributes project instructions. Additional directories do not.
• context: false in .fx.json or user settings disables project context entirely.
• Instruction files are bounded by project_instruction_file_bytes and project_instructions_total_bytes. Truncated or omitted context is reported to the runtime instead of being treated as complete, so raise the limit when a file is larger. See Context limits.
• The narrowest applicable AGENTS.md wins, so a nested file can override the repository root for calls inside its directory.

A session will not open or resume

fx doctor inspects saved sessions and names the remediation for each problem it finds. To make a separate resumable copy without touching the original:

To inspect one session without starting a turn:

A paused response can be continued with /continue in the shell, or with fx ask --resume last --continue-recovery in a headless run. See Sessions.

An MCP server is missing

While discovery runs, the status view says so; afterward it shows a secret-free health snapshot with lifecycle, authentication, and failure state.

• Native sessions read MCP servers only from ~/.fx/mcp.json. Repository-local MCP files are never loaded.
• Optional servers can fail without blocking the rest of fx. Set "required": true when the first request must wait for a ready server.
• /mcp reload validates a replacement before publishing it. Invalid configuration or a failed required server keeps the previous runtime.
• ACP sessions use only the mcpServers the client supplies and inherit nothing from your profile.

See MCP for configuration and MCP protocol reference for transport behavior.

The terminal renders incorrectly

Force terminal synchronized updates on or off to test a compatibility problem:

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

Recordings are written under ~/.fx/recordings/, and FX_RECORD=./repro.fxtape chooses an explicit path. Replay a recording before sharing it. See Share feedback.

Costs are higher than expected

fx usage reports only what fx recorded on this machine. Two features add a separate AI Gateway request beyond the selected model: automatic permission review in auto mode and the vision fallback. Both use fixed models you cannot change. See Usage and costs.

Still stuck? Share feedback with a reviewed trace attached.