BabylonJS/Babylon.js · error · Error

${context}: Irradiance coefficients are missing

Error message

${context}: Irradiance coefficients are missing

What it means

The EXT_lights_image_based extension requires each image-based light to provide irradianceCoefficients (spherical harmonics data) used to build the environment irradiance. When light.irradianceCoefficients is absent, _loadLightAsync throws, aborting scene load. The coefficients are mandatory for the loader to construct the IBL.

Source

Thrown at packages/dev/loaders/src/glTF/2.0/Extensions/EXT_lights_image_based.pure.ts:137

                light._babylonTexture = babylonTexture;

                if (light.intensity != undefined) {
                    babylonTexture.level = light.intensity;
                }

                if (light.rotation) {
                    let rotation = Quaternion.FromArray(light.rotation);

                    // Invert the rotation so that positive rotation is counter-clockwise.
                    if (!this._loader.babylonScene.useRightHandedSystem) {
                        rotation = Quaternion.Inverse(rotation);
                    }

                    Matrix.FromQuaternionToRef(rotation, babylonTexture.getReflectionTextureMatrix());
                }

                if (!light.irradianceCoefficients) {
                    throw new Error(`${context}: Irradiance coefficients are missing`);
                }

                const sphericalHarmonics = SphericalHarmonics.FromArray(light.irradianceCoefficients);
                sphericalHarmonics.scaleInPlace(light.intensity);

                sphericalHarmonics.convertIrradianceToLambertianRadiance();
                const sphericalPolynomial = SphericalPolynomial.FromHarmonics(sphericalHarmonics);

                // Compute the lod generation scale to fit exactly to the number of levels available.
                const lodGenerationScale = (imageData.length - 1) / Math.log2(light.specularImageSize);
                return await babylonTexture.updateRGBDAsync(imageData, sphericalPolynomial, lodGenerationScale);
            });
        }

        // eslint-disable-next-line github/no-then
        return light._loaded.then(() => {
            return light._babylonTexture!;
        });

View on GitHub (pinned to 0592b347b8)

Solutions

1. Add the irradianceCoefficients array (9 or 27 float SH coefficients) to the light definition
2. Re-export the environment lighting from the original tool with IBL data included
3. Remove the EXT_lights_image_based extension if baked lighting is not needed
4. Check optimizer/exporter settings so custom extension fields are preserved

Example fix

// before
"lights": [{ "type": "imagebased", "intensity": 1 }]
// after
"lights": [{ "type": "imagebased", "intensity": 1, "irradianceCoefficients": [0.1,0.1,0.1, 0.1,0.1,0.1, 0.1,0.1,0.1, ...] }]

const lights = asset.extensions?.EXT_lights_image_based?.lights ?? [];
for (const l of lights) {
  if (!Array.isArray(l.irradianceCoefficients) || l.irradianceCoefficients.length === 0) {
    throw new Error(`IBL light missing irradianceCoefficients`);
  }
}

function hasIrradiance(l: { irradianceCoefficients?: number[] }): l is { irradianceCoefficients: number[] } {
  return Array.isArray(l.irradianceCoefficients) && l.irradianceCoefficients.length > 0;
}

try {
  await BABYLON.SceneLoader.LoadAsync('./', 'env.gltf', engine);
} catch (e) {
  if (e instanceof Error && e.message.includes('Irradiance coefficients are missing')) {
    console.error('Re-export IBL with SH coefficients or remove EXT_lights_image_based');
  } else throw e;
}

When it happens

Trigger: Loading a glTF with an EXT_lights_image_based light object missing the irradianceCoefficients array in its JSON definition.

Common situations: Hand-authored environment extension blocks; exporters that emit only rotation/intensity without SH coefficients; assets stripped by optimization tools that dropped 'unknown' JSON fields.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• ${extensionContext}: Pointer is missing
• ${extensionContext}: Invalid area light type (${light.type})
• ${extensionContext}/attributes: Instance buffer accessors do
• ${extensionContext}/pointer: Interpolation is missing
• ${context}: Unsupported mode ${primitive.mode}

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