DOCUMENTATION

Troubleshooting

Most problems come down to a handful of causes that look alike from the outside. Start with python Content/Python/MifBridge/verify_install.py from the plugin folder (tools/verify_install.py in a copy from GitHub), because it tells them apart.

What verify_install says

It says What is actually wrong
the plugin answered but REFUSED the token (HTTP 403) The plugin is fine. The editor's MIF_BRIDGE_TOKEN and your MCP config disagree.
nothing is listening on port 8791 The bridge is not running. Use Tools ▸ Mif Bridge: Start.
something is listening on 8791 but it is not answering as MifBridge Another program has the port. Pick a free one with MIF_BRIDGE_PORT.
the editor at 127.0.0.1:8791 refuses the config's MIF_BRIDGE_TOKEN The token in your MCP config is not the editor's. Set it to the editor's MIF_BRIDGE_TOKEN.
its server sends to 127.0.0.1:<port>, where nothing answers The config's MIF_BRIDGE_URL or MIF_BRIDGE_PORT names the wrong port. The report names the one the editor answers on.
starts <python> ... which cannot import mcp The server's packages went into another Python. Run the pip line the check prints, which names the right one.
the server file it starts is not there The config's path is wrong, often a config written for 1.0.0. verify_install.py --fix rewrites that entry, keeping a backup of the file.
Blender addon files The add-on answers, but its installed files do not match the release, or Blender loads a second copy. Close Blender, move any extra MifBlender folders out of its add-ons folder, reinstall, and run the check again.

From 1.2 the check reads the config your MCP client reads, runs the Python that config names, and sends that config's own URL and token to the editor. It also says which piece is older than what is available, and how that copy updates. It downloads nothing, and --fix is the only change it makes.

The editor is open, but nothing answers

  • A dialog is open in the editor. From 1.2, calls made while a modal dialog is up are refused at once with modalActive: true and the dialog's title, text and buttons. Answer it in the editor, or with answer_modal_dialog in full mode. See MifBridge. After a crash, the next launch offers to restore auto-saved packages; dismiss that prompt in the editor. For disposable automation projects, see MIF_BRIDGE_AUTO_DECLINE_RECOVERY in Safety and Write Modes.
  • The bridge is stopped. Use Tools ▸ Mif Bridge: Start / Stop; the menu label shows the port when it is running.
  • A call is still running. Handlers run synchronously on the main thread, so a slow one holds the rest. The MifBridge panel shows an in-flight banner while a handler runs, and if it stays up, the endpoint it names is the one holding the editor.

A call timed out

A read that times out can simply be made again. A write whose reply timed out answers outcomeUnknown: true and retryable: false with its request id, because the editor may have applied it. request_status with that id says whether it ran and what it answered, and the identical call made again replays the first result instead of writing twice.

Your agent says the tools are unavailable

Almost always, the MCP server's dependencies were installed into a different Python from the one your client launches. verify_install.py checks exactly this. Install requirements.txt with the interpreter named in your MCP config.

A call was refused

  • ok: false with a list of accepted parameters: the call used a parameter the endpoint does not take, often a misspelling. The error names the accepted parameters and the likely correction.
  • refusedBy: "safety-gate": the current write mode does not allow this operation. See Safety and Write Modes.
  • In the panel's Activity tab, each call carries a pill:
    • BLOCKED (amber): the safety gate refused it.
    • REFUSED (grey): the request itself was invalid, such as an unknown parameter or something that does not exist. That is the system working, not a defect.
    • FAILED (red): the operation was valid, tried, and could not complete. This is the one to look at.

Blender is not answering

  • Blender is closed. The Blender tools say so and name the fix, rather than failing inside the server.
  • Two Blenders are open. Only one can hold a port; the second refuses to start its server there and says why. Compare the process id in the N-panel ▸ MifBridge tab with the one bl_status reports. If they differ, your edits are going to the other Blender. From 1.2, bl_status lists every live MifBlender, and bl_status with port or pid switches to the one you mean.
  • Blender is on another port. With the 1.2 add-on, a MifBlender on a port the server was not told about is found: when the usual port refuses and one other MifBlender is running, the refusal names it and the call that switches to it. An older add-on is not registered, so install the 1.2 zip.
  • Your changes to the add-on are not showing. Blender runs the installed copy of the add-on, not the files in your project. Reinstall the zip after updating (or, in a copy from GitHub, run python tools/sync_blender_addon.py), then restart Blender. Working from a checkout? Link it and an update is a pull and a restart.
  • MifBlender is gone from the Add-ons list after you linked it. The link points at nothing: dir /AL in Blender's add-ons folder shows its target as [..]. Delete it in Explorer and make it again from your own Command Prompt, not from inside an AI app.
  • Undo does nothing. undo_history says whether steps are being recorded and, when they are not, why: edit mode, a Mantaflow fluid domain in the file, MIF_BLENDER_UNDO=0, or Blender's Global Undo preference switched off. See MifBlender.
  • Something else is on 8792. That port belongs to the Blender add-on. If a second Unreal editor was pointed there, the port check passes but nothing works. Give that editor a different port; see Configuration.

The editor crashed during a call

MifBridge keeps a crash journal at Saved/MifBridge/journal.jsonl: one JSON record per line, written to disk before the handler runs. After a crash, open the file and look at the last session. A call with a start record and no end record is the one that was running when the editor died, and a session with no shutdown record is an editor that died rather than being closed. Each session records its process id, so several editors on one project stay separable. python Content/Python/MifBridge/mifwatch.py, run from the plugin folder, reads the journal and names that call for you.

The editor crashed when you dismissed "Missing Project Settings!"

On UE 5.3 to 5.7, Unreal shows a Missing Project Settings! notice the first time in an editor session that a mesh uses Nanite, when the project's D3D12 Targeted Shader Formats lack Shader Model 6 (SM6). The notice never closes on its own, and its Dismiss button crashes the editor once the mesh that raised it has been deleted. That is an Unreal bug, and Epic fixed it in 5.8. From 1.1, MifBridge closes the notice itself as soon as that mesh is deleted, unloaded or undone, by an agent or in the Content Browser, and says so in its reply and in the Output Log. To stop the notice appearing at all, turn SM6 on in Project Settings ▸ Platforms ▸ Windows ▸ D3D12 Targeted Shader Formats.

A vfx_look capture came back black

A known issue in 1.2. On a heavily loaded machine, some effect captures on UE 5.3 and 5.6 came back black although the effect spawned its particles. It did not reproduce on a quiet machine with the same build. Capture again once the machine is idle before treating the effect as broken.

Cooked content behaves differently

A cooked Blueprint has no graphs to read or edit, by the nature of cooking. See Cooked Projects for what works and the routes that open the rest.

Reporting a problem

The flag button in the MifBridge panel writes a structured report to Saved/MifBridge/reports/. The file holds the call and its context, and the button runs nothing else.