BabylonJS/Babylon.js · error · Error

Source channel must be between 0 and 3 (R, G, B, A)

Error message

Source channel must be between 0 and 3 (R, G, B, A)

What it means

MergeTexturesAsync combines up to four channels (R/G/B/A) from textures or constants. When a channel is a texture input, its sourceChannel selects which RGBA channel to sample and must be 0–3. This error is thrown when sourceChannel is out of range or non-integral out-of-bounds.

Source

Thrown at packages/dev/core/src/Materials/Textures/textureMerger.ts:111

 * Merge multiple texture channels into a single texture
 * @param name Name for the resulting texture
 * @param config Merge configuration
 * @param scene Scene to create the texture in
 * @returns The merged texture
 */
export async function MergeTexturesAsync(name: string, config: ITextureMergeConfiguration, scene: Scene): Promise<ProceduralTexture> {
    const channels = [config.red, config.green, config.blue, config.alpha];
    const textureInputs: BaseTexture[] = [];
    const textureInputMap: number[] = []; // Maps channel index to texture input index (-1 for constants)

    // Collect unique textures and validate inputs
    for (let channelIndex = 0; channelIndex < 4; channelIndex++) {
        const channel = channels[channelIndex];
        if (channel) {
            if (IsTextureInput(channel)) {
                // Validate source channel
                if (channel.sourceChannel < 0 || channel.sourceChannel > 3) {
                    throw new Error("Source channel must be between 0 and 3 (R, G, B, A)");
                }

                // Find or add texture to inputs
                let textureIndex = textureInputs.indexOf(channel.texture);
                if (textureIndex === -1) {
                    textureIndex = textureInputs.length;
                    textureInputs.push(channel.texture);
                }
                textureInputMap[channelIndex] = textureIndex;
            } else if (IsConstantInput(channel)) {
                // Validate constant value
                if (channel.value < 0 || channel.value > 1) {
                    throw new Error("Constant value must be between 0.0 and 1.0");
                }
                textureInputMap[channelIndex] = -1;
            } else {
                throw new Error("Invalid channel input configuration");
            }

View on GitHub (pinned to 0592b347b8)

Solutions

1. Set sourceChannel to a value in 0..3 (0=R, 1=G, 2=B, 3=A).
2. Clamp or validate any dynamically computed channel index before calling.
3. If you meant to fill the channel with a fixed value, use a constant input ({ value }) instead of a texture input.

Example fix

// before
{ texture: roughTex, sourceChannel: 4 }
// after
{ texture: roughTex, sourceChannel: 2 } // 0=R, 1=G, 2=B, 3=A

function assertValidSourceChannel(ch: { texture: unknown; sourceChannel: number }): void {
  if (!Number.isInteger(ch.sourceChannel) || ch.sourceChannel < 0 || ch.sourceChannel > 3) {
    throw new Error(`sourceChannel must be 0-3, got ${ch.sourceChannel}`);
  }
}

function hasValidSourceChannel(c: { sourceChannel: number }): c is { sourceChannel: 0 | 1 | 2 | 3 } {
  return c.sourceChannel === 0 || c.sourceChannel === 1 || c.sourceChannel === 2 || c.sourceChannel === 3;
}

try {
  const tex = await MergeTexturesAsync(inputs, width, height, scene);
} catch (e) {
  if (String(e.message).includes("Source channel must be between 0 and 3")) {
    console.error("Fix channel config: 0=R 1=G 2=B 3=A");
  }
}

When it happens

Trigger: Calling MergeTexturesAsync (directly or via CreateMergedAnisotropyTexture / glTF _convertMetalRoughFactorsToMetallicRoughnessAsync) with an ITextureMergerTextureInput whose sourceChannel is < 0 or > 3.

Common situations: Confusing sourceChannel (0–3) with the target channel index, passing -1 as a sentinel, computing the channel dynamically and going out of range, mixing up RGB index with an enum.

Related errors

• Constant value must be between 0.0 and 1.0
• Sample2DRgbaToRef: widthPx and heightPx must be positive.
• At least one mesh is needed to create the nav mesh.
• At least one mesh is needed to create the nav mesh.
• Unable to create navmesh. No navMesh or navMeshQuery returne

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