{"record":{"id":"5d11f7a5820dba01","repo":"sgl-project/sglang","slug":"mesh-generation-failed-surface-extraction-returne","errorCode":null,"errorMessage":"Mesh generation failed: surface extraction returned None. The surface level may be outside the volume data range.","messagePattern":"Mesh generation failed: surface extraction returned None\\. The surface level may be outside the volume data range\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py","lineNumber":570,"sourceCode":"        return output_path + \".obj\", output_path + \".obj\"\n\n    def forward(self, batch: Req, server_args: ServerArgs) -> Req | OutputBatch:\n        mesh_outputs = batch.extra[\"shape_meshes\"]\n        mesh = mesh_outputs[0] if isinstance(mesh_outputs, list) else mesh_outputs\n        if isinstance(mesh, list):\n            mesh = mesh[0]\n\n        if mesh is None:\n            if batch.is_warmup:\n                logger.info(\n                    \"Skipping mesh export during warmup \"\n                    \"(surface extraction returned None)\"\n                )\n                batch.extra[\"_mesh_failed\"] = True\n                if self.config.paint_enable:\n                    return batch\n                return OutputBatch(output_file_paths=[], metrics=batch.metrics)\n            raise RuntimeError(\n                \"Mesh generation failed: surface extraction returned None. \"\n                \"The surface level may be outside the volume data range.\"\n            )\n\n        if batch.is_warmup:\n            if self.config.paint_enable:\n                return batch\n            return OutputBatch(output_file_paths=[], metrics=batch.metrics)\n\n        obj_path, return_path = self._get_output_paths(batch)\n        output_dir = os.path.dirname(obj_path)\n        if output_dir:\n            os.makedirs(output_dir, exist_ok=True)\n        mesh.export(obj_path)\n\n        batch.extra[\"shape_obj_path\"] = obj_path\n        batch.extra[\"shape_return_path\"] = return_path\n","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py#L552-L588","documentation":"During mesh extraction the marching-cubes style surface extraction returned None, meaning the extracted isosurface (at the configured level value) does not intersect the volume data range — the SDF/occupancy field never crosses the surface threshold. When paint_enable is off this is fatal; with painting enabled the batch is merely flagged _mesh_failed and continues.","triggerScenarios":"num_inference_steps too low or guidance misconfigured so the denoised volume is degenerate; the surface level constant lies outside [min, max] of the produced volume; NaNs/constant volumes from a broken checkpoint or dtype issues collapse the field to a single value.","commonSituations":"Very few denoising steps producing a blob with no zero-crossing; fp16/bf16 overflow producing NaN volumes; wrong model weights or a mismatched latent shape; extreme guidance_scale values saturating the occupancy field.","solutions":["Increase num_inference_steps and use recommended guidance settings so the volume has a meaningful isosurface","Check the volume tensor for NaNs or constant values (log vol.min()/vol.max()) and verify checkpoint/dtype compatibility; switch to fp32 if NaNs appear","If using painting, set paint_enable=True so failure degrades gracefully and inspect batch.extra['_mesh_failed']","Verify latent_shape matches the model config so the decoded volume has expected range"],"exampleFix":"# before\nrun = stage.forward(batch, server_args)  # num_inference_steps=4\n\n# after\nbatch.num_inference_steps = 50  # recommended\nbatch.extra[\"shape_guidance\"] = default_guidance\nrun = stage.forward(batch, server_args)","handlingStrategy":"fallback","validationCode":"vol = decoded_volume\nif torch.isnan(vol).any() or vol.min() == vol.max():\n    raise ValueError(\"degenerate volume; increase steps / check weights\")","typeGuard":null,"tryCatchPattern":"try:\n    out = stage.forward(batch, server_args)\nexcept RuntimeError as e:\n    if \"surface extraction returned None\" in str(e):\n        batch.num_inference_steps = max(batch.num_inference_steps * 2, 50)\n        out = stage.forward(batch, server_args)  # retry once\n    else:\n        raise","preventionTips":["Use recommended num_inference_steps and guidance values","Enable paint_enable for graceful degradation","Check volumes for NaNs before mesh extraction"],"tags":["hunyuan3d","mesh-extraction","marching-cubes","degenerate-output"],"backgroundTag":"isosurface-extraction-empty","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}