BabylonJS/Babylon.js · error · Error

WebGPU shader language is only supported with WebGPU engine

Error message

WebGPU shader language is only supported with WebGPU engine

What it means

NodeMaterial supports WGSL (WebGPU shader language), but constructing one with ShaderLanguage.WGSL is only valid when the underlying engine is a WebGPU engine. Creating a WGSL NodeMaterial on WebGL throws immediately in the constructor.

Source

Thrown at packages/dev/core/src/Materials/Node/nodeMaterial.pure.ts:442

    }

    /**
     * A free comment about the material
     */
    @serialize("comment")
    public comment: string;

    /**
     * Create a new node based material
     * @param name defines the material name
     * @param scene defines the hosting scene
     * @param options defines creation option
     */
    constructor(name: string, scene?: Scene, options: Partial<INodeMaterialOptions> = {}) {
        super(name, scene || EngineStore.LastCreatedScene!);

        if (!NodeMaterial.UseNativeShaderLanguageOfEngine && options && options.shaderLanguage === ShaderLanguage.WGSL && !this.getScene().getEngine().isWebGPU) {
            throw new Error("WebGPU shader language is only supported with WebGPU engine");
        }

        this._options = {
            emitComments: false,
            shaderLanguage: NodeMaterial.DefaultShaderLanguage,
            ...options,
        };

        if (NodeMaterial.UseNativeShaderLanguageOfEngine) {
            this._options.shaderLanguage = this.getScene().getEngine().isWebGPU ? ShaderLanguage.WGSL : ShaderLanguage.GLSL;
        }

        // Setup the default processing configuration to the scene.
        this._attachImageProcessingConfiguration(null);
    }

    /**
     * Gets the current class name of the material e.g. "NodeMaterial"

View on GitHub (pinned to 0592b347b8)

Solutions

Run on a WebGPU engine (WebGPUEngine.IsSupportedAsync + WebGPUEngine creation) when using ShaderLanguage.WGSL
Choose shaderLanguage based on engine.isWebGPU: GLSL for WebGL engines
Unify with NodeMaterial.DefaultShaderLanguage rather than forcing WGSL

Example fix

// before
const mat = new NodeMaterial('m', scene, { shaderLanguage: ShaderLanguage.WGSL }); // WebGL engine
// after
const lang = scene.getEngine().isWebGPU ? ShaderLanguage.WGSL : ShaderLanguage.GLSL;
const mat = new NodeMaterial('m', scene, { shaderLanguage: lang });

Defensive patterns

Strategy: validation

Validate before calling

const shaderLanguage = scene.getEngine().isWebGPU ? ShaderLanguage.WGSL : ShaderLanguage.GLSL;
const mat = new NodeMaterial('m', scene, { shaderLanguage });

Type guard

const supportsWGSL = (engine: AbstractEngine): engine is WebGPUEngine => engine.isWebGPU;

Try / catch

try {
  return new NodeMaterial(name, scene, options);
} catch (e) {
  if (e instanceof Error && e.message.includes('WebGPU shader language')) {
    return new NodeMaterial(name, scene, { ...options, shaderLanguage: ShaderLanguage.GLSL });
  }
  throw e;
}

Prevention

Derive shader language from engine type instead of hardcoding WGSL
Feature-detect WebGPU and fail with a clear app-level message before creating materials
Keep shader language consistent across all materials in a scene

When it happens

Trigger: new NodeMaterial('m', scene, { shaderLanguage: ShaderLanguage.WGSL }) while running on a WebGLEngine (engine.isWebGPU === false), with NodeMaterial.UseNativeShaderLanguageOfEngine unset.

Common situations: Porting WebGPU projects back to WebGL or testing on browsers without WebGPU; engine type chosen at runtime (EngineFactory) but shader language hardcoded to WGSL.

Related errors

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