BabylonJS/Babylon.js · error

FrameGraphIblShadowsVoxelizationTask ${this.name}: voxel ren

Error message

FrameGraphIblShadowsVoxelizationTask ${this.name}: voxel renderer texture is unavailable

What it means

FrameGraphIblShadowsVoxelizationTask needs the voxel grid texture from its internal voxel renderer to import it into the frame graph and expose it as an output handle. This error is thrown in _updateOutputTextureHandlesFromRenderer when _voxelRenderer.getVoxelGrid().getInternalTexture() returns null, meaning the GPU-side voxel texture has not been created (or was released) at the moment record() or the voxelization observer runs.

Source

Thrown at packages/dev/core/src/FrameGraph/Tasks/Rendering/iblShadows/iblShadowsVoxelizationTask.ts:269

            bounds.min = Vector3.Minimize(bounds.min, localBounds.min);
            bounds.max = Vector3.Maximize(bounds.max, localBounds.max);
        }

        const size = bounds.max.subtract(bounds.min);
        this.voxelGridSize = Math.max(size.x, size.y, size.z);

        const halfSize = this.voxelGridSize / 2.0;
        const centerOffset = bounds.max.add(bounds.min).multiplyByFloats(-0.5, -0.5, -0.5);
        const invWorldScaleMatrix = Matrix.Compose(new Vector3(1.0 / halfSize, 1.0 / halfSize, 1.0 / halfSize), new Quaternion(), Vector3.Zero());
        const invTranslationMatrix = Matrix.Compose(new Vector3(1.0, 1.0, 1.0), new Quaternion(), centerOffset);
        invTranslationMatrix.multiplyToRef(invWorldScaleMatrix, this.worldScaleMatrix);
    }

    private _updateOutputTextureHandlesFromRenderer(): void {
        const voxelTexture = this._voxelRenderer!.getVoxelGrid();
        const voxelInternalTexture = voxelTexture.getInternalTexture();
        if (!voxelInternalTexture) {
            throw new Error(`FrameGraphIblShadowsVoxelizationTask ${this.name}: voxel renderer texture is unavailable`);
        }

        this._voxelGridTextureHandle = this._frameGraph.textureManager.importTexture(`${this.name} Voxel Grid`, voxelInternalTexture, this._voxelGridTextureHandle);
        this._frameGraph.textureManager.resolveDanglingHandle(this.outputVoxelGridTexture, this._voxelGridTextureHandle);
    }
}

View on GitHub (pinned to 0592b347b8)

Solutions

1. Ensure the IblShadows voxel renderer is fully initialized and its voxel grid created before recording the voxelization task (record after engine/scene resources are ready).
2. Verify the engine supports the required 3D texture format (WebGPU or WebGL2 with texture storage extensions) so getInternalTexture() is non-null.
3. Check that the voxel renderer was not disposed and voxelization was not disabled/disposed before record.
4. Wrap task setup in a ready-check: only add/record the task once the renderer reports ready.

Example fix

// before
frameGraph.addTask(voxelizationTask); // recorded too early
voxelizationTask.record();

// after
if (voxelizationTask._voxelRenderer.getVoxelGrid().getInternalTexture()) {
    frameGraph.addTask(voxelizationTask);
} else {
    scene.whenReadyAsync().then(() => frameGraph.addTask(voxelizationTask));
}

const voxelGrid = task._voxelRenderer?.getVoxelGrid?.();
if (!voxelGrid || !voxelGrid.getInternalTexture()) {
    throw new Error('Voxel grid GPU texture not ready; defer recording the voxelization task');
}

function hasVoxelInternalTexture(grid: unknown): grid is { getInternalTexture(): NonNullable<ReturnType<InternalTexture['getInternalTexture']>> } {
    return !!grid && typeof (grid as any).getInternalTexture === 'function' && !!(grid as any).getInternalTexture();
}

try {
    frameGraph.addTask(voxelizationTask);
} catch (e) {
    if (String(e).includes('voxel renderer texture is unavailable')) {
        scene.whenReadyAsync().then(() => frameGraph.addTask(voxelizationTask));
    } else throw e;
}

When it happens

Trigger: record() or _attachVoxelizationObserver invokes _updateOutputTextureHandlesFromRenderer while the voxel renderer's VoxelGrid has no internal (GPU) texture — e.g. the task was recorded before the engine allocated the voxel grid resource, or the texture was disposed/released.

Common situations: Recording the IBL shadows voxelization pass very early in frame-graph setup; a failed or skipped voxel grid creation due to unsupported engine/texture formats; disposing the voxel renderer but keeping the task recorded; WebGPU/WebGL capability issues preventing 3D texture allocation.

Related errors

• FrameGraphIblShadowsRendererTask "${this.name}": depthTextur
• Unable to create webGL texture
• FrameGraphDepthOfFieldBlurTask "${this.name}": sourceTexture
• FrameGraphBloomMergeTask "${this.name}": sourceTexture, circ
• FrameGraphDepthOfFieldTask: sourceTexture, depthTexture and

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