Cannot create GPU MSAA texture because underlying GPU textur

Error message

Cannot create GPU MSAA texture because underlying GPU texture is not created yet.

What it means

WebGPUHardwareTexture._createMSAATexture needs a valid underlying GPUTexture to create a multisampled copy with the same size/format. If the texture has not yet been uploaded/created on the GPU (this._webgpuTexture is undefined), Babylon throws rather than silently creating an MSAA texture with wrong properties. This guards against using render-target or sampling paths before GPU resource creation completed.

Source

Thrown at packages/dev/core/src/Engines/WebGPU/webgpuHardwareTexture.ts:143

    }

    public reset(): void {
        this._webgpuTexture = null;
        this._webgpuMSAATexture.length = 0;
        this.view = null;
        this.viewForWriting = null;
    }

    public release(): void {
        this._webgpuTexture?.destroy();
        this.releaseMSAATextures();
        this._copyInvertYTempTexture?.destroy();
        this.reset();
    }

    private _createMSAATexture(samples: number, index: number): void {
        if (!this._webgpuTexture) {
            throw new Error("Cannot create GPU MSAA texture because underlying GPU texture is not created yet.");
        }

        if (!this._webgpuMSAATexture) {
            this._webgpuMSAATexture = [];
        }

        this._webgpuMSAATexture[index] = this._engine._textureHelper.createMSAATexture(this._webgpuTexture, this.originalFormat, samples);
    }
}

View on GitHub (pinned to 0592b347b8)

Solutions

Ensure the texture is fully created/ready before rendering with MSAA: await texture.isReady() or use the onLoadedObservable callback
Check that the texture was actually uploaded (not created with noMipmap/deferred options that skip GPU creation)
Update the code ordering so the first render happens after texture load completes
If creating a render target, ensure the RT was generated (engine.createRenderTargetTexture) before MSAA helpers access it

Example fix

// before
engine.runRenderLoop(() => scene.render()); // texture may not be on GPU yet
// after
texture.onLoadObservable.addOnce(() => {
  engine.runRenderLoop(() => scene.render());
});

Defensive patterns

Strategy: validation

Validate before calling

if (!texture.isReady()) {
  await new Promise(res => texture.onLoadObservable.addOnce(res)); // or await texture.isReady() where available
}
// only then render with MSAA / access getMSAATexture

Type guard

function hasGpuTexture(hw: { _webgpuTexture?: GPUTexture }): hw is { _webgpuTexture: GPUTexture } {
  return hw._webgpuTexture != null;
}

Try / catch

try {
  scene.render();
} catch (e) {
  if (e instanceof Error && e.message.includes('underlying GPU texture is not created yet')) {
    await texture.isReady(); // retry next frame
    requestAnimationFrame(() => scene.render());
  } else throw e;
}

Prevention

Always await texture readiness (isReady / onLoadObservable) before first render
Avoid mixing deferred-load textures with MSAA render passes on frame one
Log texture._webgpuTexture presence when debugging MSAA failures
Keep texture creation and first usage in the same lifecycle phase

When it happens

Trigger: Calling engine.createTextureForCanvas / reading getMSAATexture for a texture whose GPU-side creation is deferred (e.g. data still loading, texture created with delayed GPU upload, or a dynamic/video texture not yet updated). Calling _createMSAATexture during rendering before _webgpuTexture was assigned by _createWebGPUTexture.

Common situations: Using a texture in a render pass with MSAA enabled before its image data finished loading; texture from a VideoTexture or DynamicTexture not yet initialized; race between texture load callback and first render with hardware-scaled MSAA render targets.

Related errors

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