BabylonJS/Babylon.js · error

Unsupported alpha mode: ${mode}.

Error message

Unsupported alpha mode: ${mode}.

What it means

getNativeAlphaMode converts a Babylon Constants.ALPHA_* blending mode to the native engine's ALPHA_* enum, with fallbacks for newer modes on older native runtimes. If the mode is not a recognized alpha mode at all, it throws. The library throws because the native engine cannot represent an unknown blend mode.

Source

Thrown at packages/dev/core/src/Engines/Native/nativeHelpers.ts:351

            return _native.Engine.ALPHA_MAXIMIZED;
        case Constants.ALPHA_ONEONE:
            return _native.Engine.ALPHA_ONEONE;
        case Constants.ALPHA_ONEONE_ONEONE:
            return _native.Engine.ALPHA_ONEONE_ONEONE ?? _getFallbackAlphaMode(mode, "ALPHA_ONEONE_ONEONE");
        case Constants.ALPHA_LAYER_ACCUMULATE:
            return _native.Engine.ALPHA_LAYER_ACCUMULATE ?? _getFallbackAlphaMode(mode, "ALPHA_LAYER_ACCUMULATE");
        case Constants.ALPHA_PREMULTIPLIED:
            return _native.Engine.ALPHA_PREMULTIPLIED;
        case Constants.ALPHA_PREMULTIPLIED_PORTERDUFF:
            return _native.Engine.ALPHA_PREMULTIPLIED_PORTERDUFF;
        case Constants.ALPHA_INTERPOLATE:
            return _native.Engine.ALPHA_INTERPOLATE;
        case Constants.ALPHA_SCREENMODE:
            return _native.Engine.ALPHA_SCREENMODE;
        case Constants.ALPHA_REPLACE_COLOR:
            return _native.Engine.ALPHA_REPLACE_COLOR ?? _getFallbackAlphaMode(mode, "ALPHA_REPLACE_COLOR", _native.Engine.ALPHA_COMBINE, "ALPHA_COMBINE");
        default:
            throw new Error(`Unsupported alpha mode: ${mode}.`);
    }
}

export function getNativeAttribType(type: number): number {
    switch (type) {
        case VertexBuffer.BYTE:
            return _native.Engine.ATTRIB_TYPE_INT8;
        case VertexBuffer.UNSIGNED_BYTE:
            return _native.Engine.ATTRIB_TYPE_UINT8;
        case VertexBuffer.SHORT:
            return _native.Engine.ATTRIB_TYPE_INT16;
        case VertexBuffer.UNSIGNED_SHORT:
            return _native.Engine.ATTRIB_TYPE_UINT16;
        case VertexBuffer.FLOAT:
            return _native.Engine.ATTRIB_TYPE_FLOAT;
        // HALF_FLOAT (as well as INT and UNSIGNED_INT) has no equivalent in the native bindings, which only
        // expose ATTRIB_TYPE_INT8/UINT8/INT16/UINT16/FLOAT. Those vertex attribute types are therefore
        // WebGL/WebGPU only and intentionally fall through to the throw below on the Babylon Native engine.

View on GitHub (pinned to 0592b347b8)

Solutions

1. Set material.alphaMode to a valid Constants.ALPHA_* value (e.g. Constants.ALPHA_COMBINE, Constants.ALPHA_SCREENMODE).
2. Validate the stored/loaded alphaMode against Constants before assigning.
3. Upgrade both the Babylon.js package and the native engine binaries so newer alpha modes and their fallbacks exist.

Example fix

// before
material.alphaMode = 99;
// after
material.alphaMode = Constants.ALPHA_COMBINE;

const ALPHA_MODES = new Set([BABYLON.Constants.ALPHA_DISABLE, BABYLON.Constants.ALPHA_ADD, BABYLON.Constants.ALPHA_COMBINE, BABYLON.Constants.ALPHA_SUBTRACT, BABYLON.Constants.ALPHA_MULTIPLY, BABYLON.Constants.ALPHA_MAXIMIZED, BABYLON.Constants.ALPHA_ONEONE, BABYLON.Constants.ALPHA_SCREENMODE]);
if (!ALPHA_MODES.has(mode)) throw new RangeError(`alphaMode must be a Constants.ALPHA_* value, got ${mode}`);
material.alphaMode = mode;

function isAlphaMode(v: unknown): v is number {
  const C = BABYLON.Constants;
  return typeof v === 'number' && [C.ALPHA_DISABLE, C.ALPHA_ADD, C.ALPHA_COMBINE, C.ALPHA_SUBTRACT, C.ALPHA_MULTIPLY, C.ALPHA_MAXIMIZED, C.ALPHA_ONEONE, C.ALPHA_SCREENMODE].includes(v);
}

try {
  material.alphaMode = mode;
} catch (e) {
  if (String(e.message).startsWith('Unsupported alpha mode')) {
    console.warn('Bad alphaMode, using ALPHA_COMBINE', mode);
    material.alphaMode = BABYLON.Constants.ALPHA_COMBINE;
  } else throw e;
}

When it happens

Trigger: Setting material.alphaMode (or calling setAlphaMode) with a value that is not a Constants.ALPHA_* constant, e.g. an arbitrary number, undefined, or NaN.

Common situations: Custom blend modes invented by app code; serialization restoring a corrupted alphaMode; using an alpha mode from a much newer Babylon version against an older native runtime that also lacks the fallback.

Related errors

• Unsupported stencil OpFail mode: ${opFail}.
• Unsupported stencil depthFail mode: ${depthFail}.
• Unsupported stencil opPass mode: ${opPass}.
• Unsupported attribute type: ${type}.
• SHADER ERROR" + (typeof message === "string" ? "\n" + messag

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