Troubleshooting
Common issues and how to fix them. Check the job log panel in the batch tab first — most failures include a specific error message from the MetaHuman solver.
Editor prompts to rebuild modules on every launch
The precompiled binaries do not match the installed engine version.
Either switch to the From Source installation path and rebuild against your exact engine version, or download a binary release that matches your UE version exactly.
"MHA Manager" does not appear in Tools menu
The plugin is not enabled or did not load.
Go to Edit → Plugins, search for "MHA Manager", and enable it. If it is missing from the list entirely, verify the plugin folder is in YourProject/Plugins/MHAManager/ with a valid .uplugin file.
Red X icon on a job row — validation fails
A required asset is missing or its content path cannot be resolved.
Hover over the red X for the specific validation message. Common causes: Capture Data or Identity asset was moved or renamed after being added to the queue; the Identity auto-discovery folder structure does not match the expected layout. Re-assign the asset in the affected cell.
Identity column is empty after adding a Stereo job
Auto-discovery could not find a MetaHuman Identity under a predictable folder relative to the Capture Data asset.
Assign the Identity manually by clicking the Identity cell in the job row and using the asset picker. The plugin looks for UMetaHumanIdentity assets in a sibling or parent folder named MetaHumans — reorganize your Content Browser layout to match if you want auto-discovery to work.
Stereo job fails at "GenerateDepth" stage
One or more depth generation prerequisites are missing or misconfigured.
Verify: (1) The Capture Data asset references two valid image sequences. (2) A Camera Calibration asset is assigned to the job. (3) The ImgMedia plugin is enabled. (4) The depth output directory is writable. Check the job log panel for the specific error from the depth generator.
Stereo solve quality is poor — face looks incorrect or distorted
Depth map contains holes, noise, or out-of-range values that degrade the solve.
Enable Depth Cleaning in the job's stereo options. Set Depth Clamp Min and Max to clip background noise. If the face is partially out of frame on many frames, lower Face Coverage Threshold or Face Width Threshold — or mark those frames in Frame Exclusion Ranges.
Editor crashes or becomes unresponsive during batch processing
Insufficient RAM for the number of concurrent jobs.
Set Max Concurrent Jobs back to 1 in Global Settings. Sequential processing is stable on 16 GB RAM. For concurrent jobs, 32+ GB is required per active job slot. If the crash persists on a single job, the issue is the solver itself — check Epic's MetaHuman Animator documentation for system requirements.
Solve is much slower than expected
GPU not being used, or D3D12 not active on a system that benefits from it.
Enable Force D3D12 in Global Settings and re-run. Also verify your GPU drivers are up to date and that the editor is running on the discrete GPU rather than an integrated graphics adapter (check Windows Graphics Settings → Hardware-accelerated GPU scheduling).
Batch completes but AnimSequence is not in the output path
Export AnimSequence is disabled in Global Settings, or the export step failed silently.
Check that Export AnimSequence is enabled in Global Settings. Then open the manifest at Saved/MHAManager/batch.mhajson and check the artifact state for the job — if it shows "State": "Failed" for the AnimSequence artifact, the job log will contain the export error.
AnimSequence is on the wrong skeleton or cannot be applied to the MetaHuman
Use MetaHuman ID for Output Mesh is disabled, causing export to target the generic archetype skeleton.
Enable Use MetaHuman ID for Output Mesh in Global Settings and re-export. You can re-export without re-solving: open the batch panel, select the completed job, and choose Re-export from the job context menu.
Calibration job fails immediately with "no board detected"
The board pattern settings do not match the printed checkerboard — the most common mistakes are entering inner corners instead of squares, or swapping width and height.
Board Pattern W/H is measured in squares, not inner corners. Leave Auto-Detect Board Pattern enabled — it probes your setting, its transpose, the inner-corner misentry, and Epic's shipped board (11 x 16 squares) before failing. Epic's own detection output appears in the Output Log under LogMetaHumanCalibrationGenerator.
Calibration succeeds but reconstructed depth / face scale looks wrong
The Square Size setting does not match the physical board. It cannot be measured from footage, so a wrong value silently scales the stereo baseline and all depth.
Measure a square on your printed board and set Square Size exactly (Epic's shipped board is 0.75 cm). If the probe recognizes Epic's board while your square size differs from 0.75 cm, the job log prints a hint. Re-run the calibration job after correcting it.
Calibration fails or warns about too few usable frames
The Sharpness Threshold rejected most frames — the take is motion-blurred or out of focus.
If fewer than 10 frames pass the sharpness filter, one retry runs automatically with the filter disabled, and final quality is judged by Max RMS Error (default 1.0 px). If the solve exceeds the threshold the job pauses as PoorCalibrationQuality — Accept Anyway to use it, or reshoot the checkerboard take with slower board movement and better focus for a cleaner re-solve.
Framing badge always shows "Not analyzed"
The framing probe requires UE 5.8+, the MetaHumanBodyTracker plugin installed, and the NNERuntimeORT plugin enabled in the host project. When any of these are missing, the probe quietly reports "Not analyzed".
Install Epic's free MetaHuman Animator Markerless Motion Capture plugin from Fab and enable NNERuntimeORT in Edit → Plugins. Then click Re-check next to the badge in the settings panel to re-run the probe.
Job completes with a "Body track gaps" warning
The body tracker detected the subject in fewer than 80% of frames — undetected frames export as held/reference pose.
Check the take's framing (the tracker needs the body in frame), lower Body Detection Confidence if lock is never acquired in dim or cluttered footage, or lower Body Tracking Confidence if lock drops during fast motion. The body_coverage_pct value in the manifest shows exactly how much of the take was tracked.
Commandlet exits with code 2 immediately
The commandlet failed to initialize — usually a missing manifest path or missing required plugin.
Confirm the -manifest path is an absolute filesystem path (not a content path), the file exists, and the host project has MetaHuman and CaptureData plugins enabled in its .uproject. Run with -log to see the startup error.