Troubleshooting (Pro)

Page loads but shows "Not found"

• Confirm the file exists at docs/pro/<name>.html
• Confirm the manifest path matches the filename (hyphens matter)

Density looks wrong

• Check units/scale first (Unit & Scale Doctor)
• Don't mix texel density targets across an asset set

Shading noise after cleanup

• Back off aggressive cleanup thresholds
• Scope operations (Selection Quadify) instead of global passes

LOD artifacts

• Protect silhouette-critical areas
• Validate normals stability per LOD

Mesh Import / QuadWild hangs

• QuadWild in Mesh Import runs as a non-blocking modal — the header shows current stage and elapsed time. If Blender appears to hang, check if the header still updates; a moving time counter means it is still running.
• Meshes with high-genus topology (ironwork, lattice, filigree) cause QuadWild to hang regardless of face count. Use Quadriflow (Reliable) in the Mesh Import tab instead — it auto-falls-back to QuadWild DRAFT if Quadriflow fails.
• For very dense meshes, manually decimate before running Mesh Import.

AI-generated mesh not detected

• Detection thresholds: ≥60% tris with NM≥5 and no seams, or ≥80% tris on meshes ≥200k faces, or NM≥20 with tri%≥50.
• If your mesh doesn't meet these thresholds but is AI-gen, enable Force AI-gen intake in Mesh Import settings.

Shape key error during Mesh Import

• The intake pipeline clears shape keys before modifier apply. If you see a shape key error, it means the QP_Before snapshot was active. The pipeline handles this automatically in v2.6.0+; if you're on an older version, manually remove shape keys before running Mesh Import.

UV Transfer results are poor

• Ensure the source (high-poly) and target (retopo) meshes are in the same world-space position — UV Transfer uses nearest-face projection in world space.
• Multi-material meshes with overlapping UV islands may produce inconsistent results. Inspect and re-relax individual islands in the UV Editor.

Deform Risk Check returns RED

• RED indicates high-valence poles (6+), severely uneven face density, or significant non-quad faces in likely rigging zones.
• Use Local Cleanup (if you have Ultra) or Selection Quadify in Manual Mode to fix the flagged areas before sending to a rigger.
• Note: Deform Risk is a heuristic rule-based check, not ML. It may flag areas on intentional topology (e.g. a 6-pole at a wrist joint). Use judgment before treating all RED flags as errors.