Troubleshooting

Troubleshooting

Symptom	Actual cause / fix
Invalid project path specified on launch	The --path must be absolute, not relative.
macOS: "damaged" / "unverified developer" on first launch	Releases from v0.4.0 on are Developer ID-signed + notarized (stapled) and open normally — re-download the current zip. Only pre-notarization downloads need xattr -cr MetaHumanGodot.app or System Settings → Privacy & Security → Open Anyway.
Screenshot/turntable buttons appear to do nothing (pre-mac builds)	Output dir was hardcoded to the dev tree; fixed — captures now land in ~/Pictures/MetaHumanGodot (the status bar shows the path).
Blank/black window when launched with --headless	This is an interactive GPU tool; captures run windowed and quit themselves. Drop --headless.
Turntable mp4 plays back black (older builds)	Windowed captures can come out work-area-short (odd height) and H.264 silently encodes black on odd dims. Fixed in v0.4.0 (frames are even-cropped); on older builds use mp4v or crop frames.
Custom GLB loads glassy/plastic skin	Its skin was wired into the skin shader without a roughness texture — fixed in the loader (white roughness bound). If you see it on exotic models, raise the Roughness slider.
Custom GLB loads at the wrong size / only hair visible	Mixed cm/m units inside the GLB. The loader unit-normalizes per-mesh in world space; if a model still misbehaves, re-export with consistent units.
MetaHuman face renders flat gray	Face materials wired by NAME — MetaHuman bakes mislabel surface 0 as ..Teeth_Baked.. but it's the main face skin. Wire by surface index (the shipped profiles do).
Blendshape sliders all disabled on my import	Modern MetaHumans ship no ARKit morphs (RigLogic-driven); the shapes must be baked into the GLB first. See Bring Your Own MetaHuman.
Eyes look wrong after remapping eye surfaces	Don't re-map the eye surfaces without a render check — on the bundled female character the visible eye is the corneal shell (surface 4) over the eyeball (3); "fixing" it by probe logic reads as a closed eye.
Character floats with no shadow in full-body views (pre-0.4.0)	Update: v0.4.0 adds the studio floor (SCENE → Show floor).
Presets don't seem to change the lighting in a packed build (pre-0.3.x)	Old builds loaded presets from disk paths that don't exist beside the exe; fixed — shipped presets load from the PCK.