Troubleshooting

Start with fusionctl doctor. It checks the add-in on disk, the live bridge, the running add-in's version, the sign-in and the model orientation, and exits with 1 if any check fails. A healthy setup:

ok    add-in installed        v0.1.0
ok    bridge reachable        Fusion 2705.1.30
ok    running add-in version  v0.1.0
ok    orientation             Z-up (affects which plane is the floor)

An error in one lineCopy Anchor Link

When the add-in refuses a request on purpose, the CLI prints one line, error: <command>: <reason>, and exits with 1:

error: undo: only 3 timeline item(s) exist

Any other exception inside Fusion prints Fusion raised an error (<command>). with Fusion's traceback. A failing script has its own format, see A script fails below.

The add-in is missingCopy Anchor Link

add-in installed fails with not found in <folder>: run fusionctl install. Run fusionctl install, then restart Fusion or start the add-in from Utilities > Add-Ins > FusionBridge > Run.

The add-in is outdatedCopy Anchor Link

There are two version checks, because the copy on disk and the copy running in Fusion can differ:

• add-in installed fails with v<old> on disk, CLI ships v<new>: you updated the CLI but not the add-in. Run fusionctl install and restart the add-in.
• running add-in version fails with running v<old>: the files on disk are new but Fusion still runs the old add-in. Restart it from Utilities > Add-Ins, or restart Fusion.

fusionctl ping shows the running version in its bridge line. An add-in from before version reporting shows unknown (older add-in).

The bridge is unreachableCopy Anchor Link

The CLI says Bridge unreachable on 127.0.0.1:18765. Fusion is not running, the add-in is not running, or the two use different ports. Start Fusion, check the add-in in Utilities > Add-Ins, and if you set FUSIONCTL_PORT, make sure Fusion sees the same value.

If it says No bridge token at …/token., the add-in has not created the token yet. The add-in creates the token on its first start, so it has never run with this config folder: start it, or check FUSIONCTL_CONFIG_DIR.

The token is rejectedCopy Anchor Link

The CLI says Bridge rejected the token. The add-in and the CLI read different token files. This happens when FUSIONCTL_CONFIG_DIR is set in your shell but not for Fusion (or the other way round). Make them match, then restart the add-in so it reads the token again.

A command hangs, then times outCopy Anchor Link

The add-in waits 600 seconds for Fusion, then the command fails with timeout (modal dialog open in Fusion?); if the add-in does not answer at all, the CLI gives up a little later with Fusion did not answer in time. In both cases a modal dialog is usually open in Fusion: a message box, a selection prompt, a sign-in or update window, or a dialog a script opened with ui.messageBox. While it is open Fusion's main thread does not run the bridge's requests. Close the dialog and run the command again. Scripts should print instead of opening dialogs.

A script failsCopy Anchor Link

The CLI prints error: Script failed., the traceback limited to your script's frames, and exits with 1. With --atomic it also lists the timeline items it rolled back. See When a script fails.

The part comes out ten times too largeCopy Anchor Link

The API works in centimetres. Wrap millimetre numbers in mm() or use VS("12 mm"). See Units.

The part is lying on its sideCopy Anchor Link

The script assumed the other model orientation. Check orientation in fusionctl ping: on Z-up the bed is XY, on Y-up it is XZ.

timeline says the design has no timelineCopy Anchor Link

direct-modeling design has no timeline: the active document is a direct-modelling design. Start a parametric one with fusionctl new.