Comfy-Org/ComfyUI · error · ValueError

File3DToSplat: unsupported .ksplat version {data[0]}.{data[1

Error message

File3DToSplat: unsupported .ksplat version {data[0]}.{data[1]}

What it means

Raised by _parse_ksplat_gaussian when the first header byte of a detected .ksplat file (the major version) is not 0. The parser implements the mkkellogg SplatBuffer format with major version 0 (bytes 0/1 are CurrentMajorVersion/CurrentMinorVersion); a non-zero major version means the file was written by an incompatible newer generation of the format.

Source

Thrown at comfy_extras/nodes_gaussian_splat.py:282


def _parse_splat_gaussian(data: bytes):
    # antimatter15 .splat: 32-byte records (f32 xyz, f32 scale, u8 rgba, u8 quat as (b-128)/128 wxyz).
    if len(data) % 32 != 0:
        raise ValueError("File3DToSplat: .splat size is not a multiple of 32 bytes")
    rec = np.frombuffer(data, np.dtype([('xyz', '<f4', 3), ('scale', '<f4', 3),
                                        ('rgba', 'u1', 4), ('quat', 'u1', 4)]))
    rgba = rec['rgba'].astype(np.float32) / 255.0
    rot = _norm_quat((rec['quat'].astype(np.float32) - 128.0) / 128.0)            # wxyz
    return (rec['xyz'].astype(np.float32), rec['scale'].astype(np.float32), rot,
            rgba[:, 3].copy(), _rgb_to_sh_dc(rgba[:, :3]))


def _parse_ksplat_gaussian(data: bytes):
    # mkkellogg SplatBuffer: 4096-byte header, N section headers, then per-section splat data. Supports
    # levels 0 (float) / 1 (half + bucketed positions) / 2 (half, uint8 SH). SH is skipped (base color kept).
    if data[0] != 0:
        raise ValueError(f"File3DToSplat: unsupported .ksplat version {data[0]}.{data[1]}")
    max_sections = struct.unpack_from('<I', data, 4)[0]
    level = struct.unpack_from('<H', data, 20)[0]
    if level not in _KSPLAT_COMPRESSION:
        raise ValueError(f"File3DToSplat: invalid .ksplat compression level {level}")
    bc, bs, br, bcol, bshc, default_range = _KSPLAT_COMPRESSION[level]

    parts = []
    base = 4096 + max_sections * 1024
    for s in range(max_sections):
        so = 4096 + s * 1024
        cnt = struct.unpack_from('<I', data, so + 0)[0]
        sec_max = struct.unpack_from('<I', data, so + 4)[0]
        bucket_size = struct.unpack_from('<I', data, so + 8)[0]
        bucket_count = struct.unpack_from('<I', data, so + 12)[0]
        block_size = struct.unpack_from('<f', data, so + 16)[0]
        bucket_store = struct.unpack_from('<H', data, so + 20)[0]
        scale_range = struct.unpack_from('<I', data, so + 24)[0] or default_range
        full_buckets = struct.unpack_from('<I', data, so + 32)[0]

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Re-export the file as .ply or .spz from the producing tool instead of .ksplat.
  2. Downgrade/align the producing library to a version that writes ksplat major version 0.
  3. Check ComfyUI updates: a newer build may add support for the bumped ksplat version.

Example fix

null
Defensive patterns

Strategy: try-catch

Validate before calling

data = open(path, 'rb').read()
if len(data) >= 2 and data[0] != 0:
    raise ValueError(f'ksplat major version {data[0]} unsupported (need 0.x)')

Type guard

def is_ksplat_v0(data: bytes) -> bool:
    return len(data) >= 2 and data[0] == 0 and data[1] >= 1

Try / catch

try:
    result = _parse_ksplat_gaussian(data)
except ValueError as e:
    if 'unsupported .ksplat version' in str(e):
        convert_to_ply_with_source_tool(path)
    else:
        raise

Prevention

When it happens

Trigger: File3DToSplat on a .ksplat exported by a newer version of the mkkellogg GaussianSplats3D/SplatBuffer library that bumped the major version, or on a binary that merely misdetects as ksplat (first byte 0 and second byte >= 1) but is not a ksplat at all.

Common situations: Version drift: viewer/library updated on the producing side while the parser supports only 0.x; passing an arbitrary binary whose first two bytes coincidentally match the ksplat heuristic.

Related errors

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