WebGPUComputeContext.getBindGroups: bindingsMapping is requi

Error message

WebGPUComputeContext.getBindGroups: bindingsMapping is required until browsers support reflection for wgsl shaders!

What it means

WebGPUComputeContext.getBindGroups needs a bindingsMapping (shader location map) because browsers do not yet expose reflection for WGSL shaders, so the engine cannot infer binding locations itself. Calling getBindGroups without bindingsMapping throws immediately.

Source

Thrown at packages/dev/core/src/Engines/WebGPU/webgpuComputeContext.ts:28

import * as WebGPUConstants from "./webgpuConstants";
import { type WebGPUHardwareTexture } from "./webgpuHardwareTexture";
import { type ExternalTexture } from "core/Materials/Textures/externalTexture";
import { type InternalTexture } from "core/Materials/Textures/internalTexture";

/** @internal */
export class WebGPUComputeContext implements IComputeContext {
    private static _Counter = 0;

    public readonly uniqueId: number;

    private _device: GPUDevice;
    private _cacheSampler: WebGPUCacheSampler;
    private _bindGroups: GPUBindGroup[];
    private _bindGroupEntries: GPUBindGroupEntry[][];

    public getBindGroups(bindings: ComputeBindingList, computePipeline: GPUComputePipeline, bindingsMapping?: ComputeBindingMapping): GPUBindGroup[] {
        if (!bindingsMapping) {
            throw new Error("WebGPUComputeContext.getBindGroups: bindingsMapping is required until browsers support reflection for wgsl shaders!");
        }
        if (this._bindGroups.length === 0) {
            const bindGroupEntriesExist = this._bindGroupEntries.length > 0;
            for (const key in bindings) {
                const binding = bindings[key],
                    location = bindingsMapping[key],
                    group = location.group,
                    index = location.binding,
                    type = binding.type,
                    object = binding.object;
                let indexInGroupEntries = binding.indexInGroupEntries;

                let entries = this._bindGroupEntries[group];
                if (!entries) {
                    entries = this._bindGroupEntries[group] = [];
                }

                switch (type) {

View on GitHub (pinned to 0592b347b8)

Solutions

Let the engine process the WGSL shader (use engine.createComputePipelineEffect / the standard compute dispatch path) so bindingsMapping is generated and passed.
Build and pass a bindingsMapping object ({ [bindingNameOrId]: { group, binding } }) yourself when calling getBindGroups directly.
Update Babylon.js, as newer versions construct the mapping automatically for standard compute effects.

Example fix

// before
context.getBindGroups(bindings, computePipeline); // missing mapping
// after
context.getBindGroups(bindings, computePipeline, { uniforms: { group: 0, binding: 0 }, textures: { group: 0, binding: 1 } });

Defensive patterns

Strategy: validation

Validate before calling

if (!bindingsMapping) {
  throw new Error('getBindGroups requires a bindingsMapping produced by the WGSL shader processor; use the engine compute dispatch path');
}
context.getBindGroups(bindings, computePipeline, bindingsMapping);

Type guard

function hasBindingsMapping(m: unknown): m is NonNullable<Parameters<BABYLON.WebGPUComputeContext['getBindGroups']>[2]> {
  return !!m && typeof m === 'object' && Object.keys(m as object).length > 0;
}

Try / catch

try {
  groups = context.getBindGroups(bindings, computePipeline, bindingsMapping);
} catch (e) {
  if (String(e.message).includes('bindingsMapping is required')) {
    bindingsMapping = buildBindingsMappingFromShaderProcessor(computeEffect);
    groups = context.getBindGroups(bindings, computePipeline, bindingsMapping);
  } else throw e;
}

Prevention

Dispatch compute work through the engine's standard compute effect APIs so bindingsMapping is auto-generated.
Never call WebGPUComputeContext.getBindGroups directly without a mapping from the shader processor.
Keep Babylon.js updated; newer versions improve automatic WGSL binding resolution.

When it happens

Trigger: Invoking getBindGroups (or dispatching compute work through a code path that bypasses the engine's shader processor) without supplying the bindingsMapping argument, e.g. calling low-level WebGPU compute APIs directly or with a custom pipeline whose bindings were never processed by the engine's WGSL shader processor.

Common situations: Custom compute integrations calling WebGPUComputeContext directly; skipping the engine's shader processing step that normally produces the binding map; older code written before bindingsMapping became mandatory.

Related errors

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