What causes "Kernel size must be odd." in BabylonJS/Babylon.js?

Pass an odd kernel size in the options, e.g. { kernel: 9 } instead of 8.

Kernel size must be odd.

Error message

Kernel size must be odd.

What it means

The area lights texture tool builds a Gaussian blur kernel via _generateGaussianKernel, which requires an odd size so the kernel has a unique center element (halfSize = floor(size/2)); an even size would blur asymmetrically. It deliberately rejects even sizes at construction time with this error.

Source

Thrown at packages/dev/core/src/Misc/areaLightsTextureTools.ts:170

                generateDepthBuffer: false,
                generateMipMaps: true,
                generateStencilBuffer: false,
                samplingMode: Constants.TEXTURE_TRILINEAR_SAMPLINGMODE,
                type: Constants.TEXTURETYPE_UNSIGNED_BYTE,
                format: Constants.TEXTUREFORMAT_RGBA,
            }
        );

        this._source = source;
        const engineDepthMask = this._engine.getDepthWrite(); // for some reasons, depthWrite is not restored by EffectRenderer.restoreStates
        this._renderer.render(this._effectWrapper, renderTarget);
        this._engine.setDepthWrite(engineDepthMask);
        return new BaseTexture(this._engine, renderTarget.texture);
    }

    private _generateGaussianKernel(size: number, sigma: number): KernelData {
        if (size % 2 === 0) {
            throw new Error("Kernel size must be odd.");
        }

        const kernel = new Float32Array(size);
        let sum = 0.0;
        const halfSize = Math.floor(size / 2);

        for (let i = -halfSize; i <= halfSize; ++i) {
            const value = Math.exp(-(i * i) / (2.0 * sigma * sigma));
            const index = i + halfSize;
            kernel[index] = value;
            sum += value;
        }

        for (let i = 0; i < kernel.length; i++) {
            kernel[i] /= sum;
        }

        return { kernel, kernelSize: size, kernelHalfSize: halfSize };

View on GitHub (pinned to 0592b347b8)

Solutions

Pass an odd kernel size in the options, e.g. { kernel: 9 } instead of 8.
If the size comes from input/config, coerce it before constructing: size % 2 === 0 ? size + 1 : size.
Prefer typical odd sizes like 3, 5, 7, 9 unless a larger odd kernel is specifically required.
Check the call site (constructor / AreaLightsLCDTexture options) to find where the even value originates.

Example fix

// before
const tool = createTool({ kernel: 8 }); // throws
// after
const kernel = 8 % 2 === 0 ? 9 : 8; // ensure odd
const tool = createTool({ kernel });

Defensive patterns

Strategy: validation

Validate before calling

function assertOddKernel(size) {
  if (size % 2 === 0) {
    throw new Error('Kernel size must be odd, got ' + size);
  }
  return size;
}
const tool = createAreaLightsTool({ kernel: assertOddKernel(options.kernel) });

Type guard

function isOddKernelSize(size) {
  return Number.isInteger(size) && size > 0 && size % 2 === 1;
}

Try / catch

try {
  const tool = new AreaLightsTextureTool(engine, options);
} catch (e) {
  if (String(e.message).includes('Kernel size must be odd')) {
    options.kernel = options.kernel % 2 === 0 ? options.kernel + 1 : options.kernel;
    // retry with corrected options
  } else { throw e; }
}

Prevention

Always use odd sizes (3, 5, 7, 9...) for Gaussian blur kernels.
Coerce user/config-supplied sizes with size % 2 === 0 ? size + 1 : size before use.
Don't reuse power-of-two texture dimensions as blur kernel sizes.
Clamp UI sliders controlling kernel size to odd values only.
Add a startup assert when the kernel size comes from configuration.

When it happens

Trigger: Constructing the area lights texture tool (e.g. via AreaLightsTextureToolsFactory or helpers like AreaLightsLCDTexture) with options.kernel set to an even number such as 8 or 16.

Common situations: Choosing a power-of-two size 'for performance' and forgetting blurs need odd sizes; kernel size read from config or a slider that permits even values; reusing a size constant from elsewhere (e.g. texture dimensions) as the blur kernel size.

Related errors

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