Connector troubleshooting

Problems divide cleanly into two kinds, and telling them apart takes one question.

Ask Claude whether HullForge is connected. The hf_bridge_status tool runs inside the connector, so it answers even when no editor is running. What it says tells you which half to look at.

Nothing at all is listed

Not even hf_bridge_status. The connector itself did not start.

• Check Claude Desktop’s connector settings and confirm HullForge is installed and enabled.
• Reinstall HullForge.mcpb.
• The connector needs no Python, no runtime, and no configuration, so a failure here is an install problem rather than an environment one.

Only the connector’s own tools are listed

You see hf_bridge_status and hf_list_tool_areas and nothing else. Both are implemented in the connector, so this pair with nothing after it means the connector is fine and it cannot see an editor.

• Is a project open in Unreal 5.5, 5.6, 5.7 or 5.8?
• Is the plugin enabled, under Edit > Plugins > Editor?
• Did the editor finish loading? The bridge starts with the editor, not with the splash screen.

Open the project and the remaining tools appear within a second or two. You do not need to restart Claude. If they do not, ask for the bridge status again and read what it reports.

Tools are listed but every call fails

The connector can see a session file but cannot reach the editor behind it.

• Most often the editor is busy. A landscape import or a shader compile holds the game thread, and calls queue behind it.
• Ask for the editor state. Shader jobs still compiling explains a great deal.
• If the editor was force-killed, a stale session file can survive. It is swept on the next editor start, and clients check the process id, so this resolves itself.

There is no port setting in Claude

This is intentional, not an omission.

The connector has no configuration at all: no port, no host, no token. Each editor writes the port it actually bound into its session file, and the connector reads it from there. A second setting on the Claude side could disagree with the editor, and there would be nothing on screen to say which was wrong.

The port is set in the editor, at Project Settings > Plugins > HullForge > Port. Changing it needs no change anywhere else.

Port is already in use

Set Port to 0 in Project Settings > Plugins > HullForge. The operating system picks a free one and the connector still finds it, because discovery does not depend on a fixed port.

Two editors open, wrong project

The connector prefers the editor it is already connected to, so a second editor opening does not silently move the target mid-conversation. Ask for the bridge status to see every editor it can find and which one is active.

A call reported success but nothing changed

This should not happen, and it is worth reporting.

Every write is re-read from the object and compared, so a mutation that did not take effect is supposed to be reported as a failure. A success that was not real is a bug in HullForge rather than expected behaviour. Send it to support@jigwright.com with the tool name and the arguments.

Still stuck

Email support@jigwright.com with your Unreal version, your operating system, and what the bridge status tool reported. If a tool returned an error, paste it verbatim: the messages are written to name the cause and the fix, so the text itself is usually the most useful thing you can send.