Troubleshooting

The client cannot connect

Open Fanta and focus a design before starting the stdio bridge. Use Help → Connect Claude Code / Codex… to copy the command for this running executable, including its --user-data-dir value. Check fanta_live_mcp.enabled, restart the client, and call get_editor_state. The bridge exits when the app is closed or MCP is disabled.

The documented bridge is for non-Store builds. If you are configuring an MCP server inside Fanta, check Settings → MCP & Tools for its status, scope, and connection type. A Mac App Store feature build cannot launch a local command-backed server; use a remote HTTP server there. External-client bridging to a packaged Store build has not been verified.

An in-app HTTP MCP server cannot authenticate

The configured Fanta-hosted fanta (/mcp) and fanta-design (/v2/mcp) connections use your signed-in Fanta account when their endpoints match the configured account backend and no explicit Authorization or x-api-key header overrides it. If one returns 401, sign out and sign in to Fanta again. An ordinary startup timeout does not clear a separate cached OAuth session for that endpoint; check the server status and network before changing credentials.

Other HTTP MCP servers can use their own OAuth flow. If such a server fails to start without an authentication challenge while a cached OAuth session exists, Fanta can clear that server's stale session and rediscover authorization. A server configured with an explicit authentication header uses that header instead; check its value after a 401. These rules concern servers used by Fanta's in-app agent, not the local fanta --mcp-stdio bridge used by external agents. The managed-server failure paths have isolated tests; production service recovery remains unverified.

The wrong design is active

get_editor_state reports the active page and selection. Focus the intended design and read state again. The server acts on the most recently focused canvas.

A tree query is refused

batch_get has two separate limits. A page listing that would traverse more than 1,000 nodes is refused before its response is built; lower depth, reduce limit and advance offset, or fetch relevant exact IDs. A response over 256 KiB is also refused; request fewer nodes or use detail: "summary" instead of "style". A wide imported .fig page can have thousands of siblings.

Source looks incomplete

read_fnx_source returns at most 64 KiB by default. Its offset is a 1-based line number. Follow truncated and next_offset; use a larger max_bytes for an unusually long line (ceiling 1 MiB). Never replace a file based on a partial slice.

Source did not reload

Validate a complete candidate with validate_fnx_source, save the .fnx or managed JSON file in the open project, and allow the reload. An identity sidecar such as page.ids.json can be edited, but preserve existing node IDs and validate the complete project before saving; a parseable JSON file alone may still be invalid. Fanta logs live at ~/Library/Logs/Fanta/.

Finish an active canvas preview or unsaved Code draft before trying to reload the same source. Fanta keeps the last valid canvas if an external source edit cannot be parsed and reports a conflict; repair the file and let the watcher reload it. If you are using the Code workspace, Discard draft reloads only the selected FNX or JSON buffer from disk. Saving source can also fail when canvas changes are unsaved, the file changed on disk, or another source save or discard is in progress; resolve that state and retry.

Code reports a source refresh warning

A 12 October 2026 recording on signed Build45 showed Could not refresh saved source: oneshot canceled in the Code workspace after a canvas Save. In that case, the saved FNX retained the edited CTA and helper text; closing and reopening the project restored a clean source view. The cause and frequency are not established, and this recovery does not prove every refresh warning is harmless.

Verify that the saved source contains the expected change and resolve any unsaved canvas or Code drafts before closing. Reopen the same project before making further source edits. If the warning persists, a save fails, or the saved source and canvas disagree, stop editing and report the app version, macOS, steps and exact warning through the support links on the download page. Remove secrets and private project content from any logs or screenshots you share.

A canvas change appears, but the source did not save

Check the editor's save error and the project diff. A delete or node-type change can be refused at persistence time when an authored FNX attribute would be lost and canvas Undo could not restore it. Undo that canvas change, or edit the FNX source to remove the attribute intentionally, validate it, and retry. Structural saves also refuse a rewrite that cannot retain authored FNX comments. Do not treat a successful batch_design response as proof that autosave reached disk.