Troubleshooting

Start with the symptom that best matches the problem. Check the first CAT-related error before later warnings.

Installation issues

CAT does not appear in the editor

• Confirm that the plugin is located in <Project>/Plugins/CAT or the engine plugin directory.
• Confirm that the project is running Unreal Engine 5.7.
• Check Edit > Plugins and enable Customizable Assembly Toolkit.
• Restart Unreal Editor after enabling the plugin or compiling it.

The project fails to compile

• Check that the engine version matches the plugin's supported version.
• Rebuild the project after adding the plugin.
• Review the first CAT-related compile error in the build log; later errors often follow from it.

Assembly does not initialize

• Verify that Source Asset is assigned.
• Verify that the assigned object is a valid CAT Part Model or Assembly source asset.
• Open the source asset and resolve validation errors.
• Test first on the server in a networked project.
• Check the Output Log for CAT messages after play begins.

Physics does not start

• Confirm that initialization succeeded before calling Enter Simulation.
• Check Auto Enter Simulation on the CAT Assembly Actor.
• Verify the Part Model has valid mesh, collision, body, and mass settings.
• Check the Assembly validation panel for invalid connector or actuator references.

Grab does not find a target

• Confirm the player owns an active CAT Grab Component.
• Confirm the target Assembly allows Grab and has its Grabbable Component.
• Check trace distance, collision channels, and view direction.
• Confirm an active Control Session is not blocking the interaction.

Connectors do not snap

• Confirm the grabbed Part and target have unoccupied connectors.
• Check connector distance and angular tolerances.
• Verify connector frames and alignment modes in the Part Model Editor.
• Check the placement ghost validity state before releasing.

Controller input does not work

• Confirm the Control Station selects the intended Controller class.
• Assign an Input Action to each required Controller input slot.
• Match the Input Action value type to the slot type.
• Use On Controller Update, not general Event Tick, for Controller output.
• Reacquire actuator handles after structural changes.

Buoyancy does not work

• Enable the Unreal Engine Water plugin.
• Confirm that the test level contains a valid water body.
• Verify that the assembly is initialized and has entered simulation.

Client does not receive updates

• Perform structural changes on the server, not on a client.
• Confirm that the actor is replicated for the intended clients.
• Test with a fresh client connection after the server has created the assembly.
• Submit client commands through a player-owned Assembly Interactor Component.
• Test join in progress separately from initial connection.

Reporting an issue

Include the following information in a support request:

• CAT version and Unreal Engine version
• Whether the issue occurs in standalone, listen-server, or dedicated-server play
• Reproduction steps
• Output Log messages and a screenshot or short video when useful
• The affected Part Model or Assembly validation result