What causes "Initial color gradient values not found in context." in BabylonJS/Babylon.js?

Ensure the particle system being converted has its initial color gradient (index 0) value defined so the conversion creates colorGradientValue0Output before processing color gradients.

BabylonJS/Babylon.js · error

Initial color gradient values not found in context.

Error message

Initial color gradient values not found in context.

What it means

When converting a legacy particle system to a Node Particle System, the helper builds a gradient-based color computation for particles that have color gradients over their lifetime. It requires a prior block group that computes the gradient's endpoint value at gradient index 0 to already exist in the shared RuntimeConversionContext. If that output slot is undefined, the conversion cannot wire the gradient inputs, so it throws instead of producing a broken graph.

Source

Thrown at packages/dev/core/src/Particles/Node/nodeParticleSystemSet.helper.ts:518

    return updatedParticle;
}

/**
 * Creates the group of blocks that represent the particle color update
 * @param inputParticle The input particle to update
 * @param colorGradients The color gradients (if any)
 * @param context The context of the current conversion
 * @returns The output of the group of blocks that represent the particle color update
 */
function _UpdateParticleColorBlockGroup(
    inputParticle: NodeParticleConnectionPoint,
    colorGradients: Nullable<Array<ColorGradient>>,
    context: RuntimeConversionContext
): NodeParticleConnectionPoint {
    let colorCalculation: NodeParticleConnectionPoint | undefined;
    if (colorGradients && colorGradients.length > 0) {
        if (context.colorGradientValue0Output === undefined) {
            throw new Error("Initial color gradient values not found in context.");
        }

        context.ageToLifeTimeRatioBlockGroupOutput = _CreateAgeToLifeTimeRatioBlockGroup(context);
        colorCalculation = _CreateGradientBlockGroup(context.ageToLifeTimeRatioBlockGroupOutput, colorGradients, ParticleRandomBlockLocks.OncePerParticle, "Color", [
            context.colorGradientValue0Output,
        ]);
    } else {
        colorCalculation = _BasicColorUpdateBlockGroup();
    }

    // Create the color update block clamping alpha >= 0
    const colorUpdateBlock = new UpdateColorBlock("Color update");
    inputParticle.connectTo(colorUpdateBlock.particle);
    _ClampUpdateColorAlpha(colorCalculation).connectTo(colorUpdateBlock.color);

    return colorUpdateBlock.output;
}

View on GitHub (pinned to 0592b347b8)

Solutions

Ensure the particle system being converted has its initial color gradient (index 0) value defined so the conversion creates colorGradientValue0Output before processing color gradients.
Update to a Babylon.js version where conversion of color gradients is fixed if your system data is valid but still triggers this.
As a workaround, remove or simplify colorGradients so the conversion path that requires the gradient-0 output is not taken, then rebuild the node graph manually.

Example fix

// before: particle with colorGradients but no gradient[0] start value
const ps = new ParticleSystem("p", 1000, scene);
ps.addColorGradient(0.5, new Color4(1, 0, 0, 1)); // no gradient at 0
// after: define gradient at t=0 so the initial-value block group is created
ps.addColorGradient(0, new Color4(1, 1, 1, 1));
ps.addColorGradient(0.5, new Color4(1, 0, 0, 1));

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a gradient exists at t=0 before converting to node particles
const hasInitialGradient = ps.colorGradients?.some(g => g.gradient === 0);
if (!hasInitialGradient) throw new Error("ParticleSystem needs a color gradient at 0 before node conversion");

Type guard

function hasColorGradient0(ps: ParticleSystem): boolean {
  return Array.isArray(ps.colorGradients) && ps.colorGradients.some(g => g.gradient === 0);
}

Prevention

Always define color gradients starting at factor 0.
Avoid invoking node-system-set conversion helpers directly with a hand-built context.
Pin Babylon.js versions when serializing/converting particle systems across environments.

When it happens

Trigger: Calling _UpdateParticleColorBlockGroup (via the node-particle-system-set conversion of aParticleSystem with colorGradients) when context.colorGradientValue0Output is undefined — i.e. the initial color gradient value block group was never created during conversion of the particle system's constant/initial color properties.

Common situations: Converting a ParticleSystem whose color gradient setup skips the initial color step (e.g. a hand-built or hand-edited particle config, or a system variant whose constantColor/gradient0 setup path is not run), typically from serialization drift or a custom conversion entry point.

Related errors

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