Comfy-Org/ComfyUI · error · ValueError

Unsupported splat format: {format!r}

Error message

Unsupported splat format: {format!r}

What it means

Raised by SplatToFile3D.execute when the requested format string has no registered writer in FORMAT_WRITERS. The node exposes a combo (ply / ksplat / spz, plus the built-in splat writer) and looks the writer up by exact string; any other value — typo, wrong case, or a format only supported for reading — hits this error.

Source

Thrown at comfy_extras/nodes_gaussian_splat.py:504

            category="3d/splat",
            description="Serialize a gaussian splat to a File3D object for Save / Preview 3D nodes. "
                        "Supports one item per batch only.",
            inputs=[
                IO.Splat.Input("splat"),
                IO.Combo.Input("format", options=list(cls.FORMAT_WRITERS),  # TODO: add "splat" when we have a writer for it
                               tooltip="ply: standard 3D Gaussian Splat with full spherical harmonics. "
                                       "ksplat: mkkellogg SplatBuffer (level 0, uncompressed), base color only "
                                       "spz: Niantic gzip-compressed (~10x smaller), base color only "
                                       ),
            ],
            outputs=[IO.File3DSplatAny.Output(display_name="model_3d")],
        )

    @classmethod
    def execute(cls, splat, format="ply") -> IO.NodeOutput:
        writer = cls.FORMAT_WRITERS.get(format)
        if writer is None:
            raise ValueError(f"Unsupported splat format: {format!r}")

        if splat.positions.shape[0] > 1:
            logging.warning("SplatToFile3D supports one item per batch only. Got %d; using first.", splat.positions.shape[0])
        end = _real_len(splat, 0)
        data = writer(splat.positions[0, :end], splat.scales[0, :end],
                      splat.rotations[0, :end], splat.opacities[0, :end], splat.sh[0, :end])
        return IO.NodeOutput(Types.File3D(BytesIO(data), file_format=format))


class File3DToSplat(IO.ComfyNode):
    @classmethod
    def define_schema(cls):
        return IO.Schema(
            node_id="File3DToSplat",
            display_name="Get Splat",
            search_aliases=["load splat", "ply to splat", "import splat", "file to splat"],
            category="3d/splat",
            description="Parse a splat File3D into a gaussian splat. Inverse of Create 3D File (from Splat). "

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Use one of the exact advertised values: "ply", "ksplat", or "spz".
  2. If loading an old workflow, re-pick the format in the node UI and re-save.
  3. In API scripts, validate the format against the node's combo list before submitting the prompt.

Example fix

// before
SplatToFile3D().execute(splat, format="PLY")

// after
SplatToFile3D().execute(splat, format="ply")
Defensive patterns

Strategy: validation

Validate before calling

VALID = set(SplatToFile3D.FORMAT_WRITERS)  # {'ply','ksplat','spz', ...}
if format not in VALID:
    raise ValueError(f'format must be one of {sorted(VALID)}, got {format!r}')

Type guard

def is_writable_splat_format(fmt: str) -> bool:
    return fmt in SplatToFile3D.FORMAT_WRITERS

Try / catch

try:
    out = SplatToFile3D().execute(splat, format=format)
except ValueError as e:
    if 'Unsupported splat format' in str(e):
        format = 'ply'  # safest default
        out = SplatToFile3D().execute(splat, format=format)
    else:
        raise

Prevention

When it happens

Trigger: Calling SplatToFile3D programmatically (or via a hand-built workflow/API request) with a format value outside the combo, e.g. "splat " with trailing space, "PLY", or a format the node can read but not write. Frontend combo users normally cannot trigger it; JSON-submitted prompts with a stale/edited combo value can.

Common situations: Workflows saved with a format value from an older/newer node version; API scripts passing an unvalidated string; combo value edited directly in the workflow JSON.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/ebe321abe762f539. Report an issue: GitHub.