BabylonJS/Babylon.js · error · Error

${extensionContext}: Gaussian splatting primitives must use

Error message

${extensionContext}: Gaussian splatting primitives must use POINTS mode

What it means

The KHR_gaussian_splatting glTF extension loader only supports primitives whose rendering mode is POINTS (mode 0), since splats are rendered as point clouds. When a gaussian-splatting mesh primitive declares any other primitive mode (triangles, lines, etc.), the loader throws immediately in _loadMeshPrimitiveAsync to prevent silently rendering the splat data incorrectly.

Source

Thrown at packages/dev/loaders/src/glTF/2.0/Extensions/KHR_gaussian_splatting.pure.ts:75

    public dispose(): void {
        (this._loader as any) = null;
    }

    /**
     * @internal
     */
    // eslint-disable-next-line no-restricted-syntax
    public _loadMeshPrimitiveAsync(
        context: string,
        name: string,
        node: INode,
        mesh: IMesh,
        primitive: IMeshPrimitive,
        assign: (babylonMesh: AbstractMesh) => void
    ): Nullable<Promise<AbstractMesh>> {
        return GLTFLoader.LoadExtensionAsync<IKHRGaussianSplatting, AbstractMesh>(context, primitive, this.name, async (extensionContext) => {
            if (primitive.mode != undefined && primitive.mode !== MeshPrimitiveMode.POINTS) {
                throw new Error(`${extensionContext}: Gaussian splatting primitives must use POINTS mode`);
            }

            const loader = this._loader;

            const loadAttribute = (attributeName: string): Nullable<Promise<Float32Array>> => {
                const accessorIndex = primitive.attributes[attributeName];
                if (accessorIndex == undefined) {
                    return null;
                }
                const accessor = ArrayItem.Get(`${context}/attributes/${attributeName}`, loader.gltf.accessors, accessorIndex) as IAccessor;
                return loader._loadFloatAccessorAsync(`/accessors/${accessor.index}`, accessor);
            };

            const positionsPromise = loadAttribute("POSITION");
            if (!positionsPromise) {
                throw new Error(`${extensionContext}: Gaussian splatting primitive is missing the POSITION attribute`);
            }

View on GitHub (pinned to 0592b347b8)

Solutions

1. Set "mode": 0 (POINTS) on the gaussian splatting mesh primitive in the glTF JSON
2. Re-export the asset with a converter that emits POINTS mode for KHR_gaussian_splatting primitives
3. If the primitive is not actually a splat, remove the KHR_gaussian_splatting extension from that primitive

Example fix

// before
"primitives": [{ "attributes": { "POSITION": 0 }, "mode": 4, "extensions": { "KHR_gaussian_splatting": {} } }]
// after
"primitives": [{ "attributes": { "POSITION": 0 }, "mode": 0, "extensions": { "KHR_gaussian_splatting": {} } }]

function validateSplatPrimitive(primitive) {
  if (primitive.mode !== undefined && primitive.mode !== 0 /* POINTS */) {
    throw new Error(`KHR_gaussian_splatting primitive must use POINTS mode (got ${primitive.mode})`);
  }
}
// run for each primitive of each mesh before loader.loadAsync

const isPointsMode = (p: { mode?: number }): p is { mode: 0 } => p.mode === undefined || p.mode === 0;

try {
  await loader.loadAsync(url);
} catch (e) {
  if (e instanceof Error && e.message.includes("must use POINTS mode")) {
    console.error("Asset has gaussian-splatting primitive with non-POINTS mode; re-export it.");
  } else throw e;
}

When it happens

Trigger: Loading a .gltf/.glb that uses the KHR_gaussian_splatting extension on a mesh primitive whose 'mode' property is defined and is not 0 (POINTS), e.g. mode 4 (TRIANGLES) exported by a splat-to-glTF converter.

Common situations: Using a converter/exporter that defaults primitives to TRIANGLES while attaching the gaussian splatting extension; hand-editing glTF JSON and forgetting mode:0; a spec update changing mode requirements so older assets no longer load.

Related errors

• ${extensionContext}: Gaussian splatting primitive is missing
• Buffer access is out of range
• ${extensionContext}: Invalid area light type (${light.type})
• ${context}: Irradiance coefficients are missing
• ${extensionContext}/attributes: Instance buffer accessors do

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/e23352a16fea2858. Report an issue: GitHub.