BabylonJS/Babylon.js · error

Unsupported stencil opPass mode: ${opPass}.

Error message

Unsupported stencil opPass mode: ${opPass}.

What it means

getNativeStencilDepthPass maps the stencil depth-pass (opPass) constant to the Babylon Native STENCIL_OP_PASS_Z_* enum. Unknown opPass values passed through applyStencil reach the switch default and throw. It enforces that only recognized stencil ops reach the native engine.

Source

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

    switch (opPass) {
        case Constants.KEEP:
            return _native.Engine.STENCIL_OP_PASS_Z_KEEP;
        case Constants.ZERO:
            return _native.Engine.STENCIL_OP_PASS_Z_ZERO;
        case Constants.REPLACE:
            return _native.Engine.STENCIL_OP_PASS_Z_REPLACE;
        case Constants.INCR:
            return _native.Engine.STENCIL_OP_PASS_Z_INCR;
        case Constants.DECR:
            return _native.Engine.STENCIL_OP_PASS_Z_DECR;
        case Constants.INVERT:
            return _native.Engine.STENCIL_OP_PASS_Z_INVERT;
        case Constants.INCR_WRAP:
            return _native.Engine.STENCIL_OP_PASS_Z_INCRSAT;
        case Constants.DECR_WRAP:
            return _native.Engine.STENCIL_OP_PASS_Z_DECRSAT;
        default:
            throw new Error(`Unsupported stencil opPass mode: ${opPass}.`);
    }
}

const _warnedUnsupportedAlphaModes = new Set<number>();

// Some alpha modes were introduced alongside newer Babylon Native features. When running against an older
// native binary the corresponding _native.Engine constant is undefined; warn once and use a supported fallback.
function _getFallbackAlphaMode(mode: number, unsupportedName: string, fallback = _native.Engine.ALPHA_ONEONE, fallbackName = "ALPHA_ONEONE"): number {
    if (!_warnedUnsupportedAlphaModes.has(mode)) {
        _warnedUnsupportedAlphaModes.add(mode);
        Logger.Warn(`Alpha mode ${unsupportedName} is not supported by this version of Babylon Native; falling back to ${fallbackName}.`);
    }
    return fallback;
}

export function getNativeAlphaMode(mode: number): number {
    switch (mode) {
        // AbstractEngine initializes/resets _alphaMode to -1 as an "unset" sentinel (see

View on GitHub (pinned to 0592b347b8)

Solutions

1. Use Constants stencil op values (KEEP, ZERO, REPLACE, INCR, DECR, INVERT, INCR_WRAP, DECR_WRAP) for opPass.
2. Validate all four applyStencil arguments against Constants before the call.
3. Update Babylon.js if the required op mapping is absent from your version.

Example fix

// before
engine.applyStencil(true, Constants.KEEP, Constants.KEEP, 0x1E00); // GL_KEEP
// after
engine.applyStencil(true, Constants.KEEP, Constants.KEEP, Constants.KEEP);

const OPS = [BABYLON.Constants.KEEP, BABYLON.Constants.ZERO, BABYLON.Constants.REPLACE, BABYLON.Constants.INCR, BABYLON.Constants.DECR, BABYLON.Constants.INVERT, BABYLON.Constants.INCR_WRAP, BABYLON.Constants.DECR_WRAP];
if (!OPS.includes(opPass)) throw new RangeError(`opPass must be a Constants stencil op, got ${opPass}`);

function isStencilOp(v: unknown): v is number {
  const C = BABYLON.Constants;
  return typeof v === 'number' && [C.KEEP, C.ZERO, C.REPLACE, C.INCR, C.DECR, C.INVERT, C.INCR_WRAP, C.DECR_WRAP].includes(v);
}

try {
  engine.applyStencil(face, opFail, depthFail, opPass);
} catch (e) {
  if (String(e.message).includes('opPass mode')) {
    console.warn('Bad opPass, using KEEP', opPass);
    engine.applyStencil(face, opFail, depthFail, BABYLON.Constants.KEEP);
  } else throw e;
}

When it happens

Trigger: Calling engine.applyStencil(faceMode, opFail, depthFail, opPass) with an opPass value that is not a Constants stencil op constant, e.g. a raw GL value or null.

Common situations: Magic-number stencil configuration; copy-paste of WebGL renderer code into a Babylon Native project; accidentally passing a face mode or comparison function into the opPass slot.

Related errors

• Unsupported stencil OpFail mode: ${opFail}.
• Unsupported stencil depthFail mode: ${depthFail}.
• Unsupported alpha mode: ${mode}.
• 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/f34691363ac20f11. Report an issue: GitHub.