mrdoob/three.js · error · Error

THREE.PMREMGenerator: .fromEquirectangular() called before t

Error message

THREE.PMREMGenerator: .fromEquirectangular() called before the backend is initialized. Use "await renderer.init();" before using this method.

What it means

Thrown by PMREMGenerator.fromEquirectangular() when the renderer is not yet initialized. The method converts an equirectangular texture into a PMREM cubemap, which requires the GPU backend; _hasInitialized delegates to renderer.hasInitialized().

Source

Thrown at src/renderers/common/extras/PMREMGenerator.js:217

	}

	/**
	 * Generates a PMREM from an equirectangular texture, which can be either LDR
	 * or HDR. The ideal input image size is 1k (1024 x 512), as this matches best
	 * with the 256 x 256 cubemap output. The minimum supported input image size
	 * is 64 x 32.
	 *
	 * @param {Texture} equirectangular - The equirectangular texture to be converted.
	 * @param {?RenderTarget} [renderTarget=null] - The render target to use.
	 * @return {RenderTarget} The resulting PMREM.
	 * @see {@link PMREMGenerator#fromEquirectangularAsync}
	 */
	fromEquirectangular( equirectangular, renderTarget = null ) {

		if ( this._hasInitialized === false ) {

			throw new Error( 'THREE.PMREMGenerator: .fromEquirectangular() called before the backend is initialized. Use "await renderer.init();" before using this method.' );

		}

		return this._fromTexture( equirectangular, renderTarget );

	}

	/**
	 * Generates a PMREM from an equirectangular texture, which can be either LDR
	 * or HDR. The ideal input image size is 1k (1024 x 512),
	 * as this matches best with the 256 x 256 cubemap output.
	 *
	 * @deprecated
	 * @param {Texture} equirectangular - The equirectangular texture to be converted.
	 * @param {?RenderTarget} [renderTarget=null] - The render target to use.
	 * @return {Promise<RenderTarget>} The resulting PMREM.
	 * @see {@link PMREMGenerator#fromEquirectangular}
	 */

View on GitHub (pinned to da05705fa3)

Solutions

Call `await renderer.init();` before `pmrem.fromEquirectangular(tex)`.
Use the deprecated `await pmrem.fromEquirectangularAsync(tex)` (inits internally).
Ensure the input texture is itself initialized (renderer.initTexture) and the renderer is initialized before PMREM conversion.

Example fix

// before
const renderer = new WebGPURenderer();
const pmrem = new PMREMGenerator(renderer);
const envMap = pmrem.fromEquirectangular(hdrTexture); // throws

// after
const renderer = new WebGPURenderer();
await renderer.init();
const pmrem = new PMREMGenerator(renderer);
const envMap = pmrem.fromEquirectangular(hdrTexture);

Defensive patterns

Strategy: validation

Validate before calling

async function safeFromEquirect(pmrem, tex) {
  if (!pmrem._renderer.hasInitialized()) await pmrem._renderer.init();
  return pmrem.fromEquirectangular(tex);
}

Type guard

function pmremReady(pmrem) {
  return pmrem._renderer && typeof pmrem._renderer.hasInitialized === 'function' && pmrem._renderer.hasInitialized();
}

Try / catch

try {
  return pmrem.fromEquirectangular(tex);
} catch (e) {
  if (/fromEquirectangular\(\) called before/.test(e.message)) { await pmrem._renderer.init(); return pmrem.fromEquirectangular(tex); }
  else throw e;
}

Prevention

Await renderer.init() before any PMREM conversion.
When loading HDR with RGBELoader, perform the PMREM step in a post-init async phase.
Gate with renderer.hasInitialized() in your environment-loading helper.

When it happens

Trigger: Calling `pmrem.fromEquirectangular(equirectTexture)` on a PMREMGenerator whose renderer has not yet had `await renderer.init()` resolve. Typical in HDR environment loading flows.

Common situations: Loading an HDR/equirect environment with RGBELoader then converting to PMREM at startup. Migrating from the deprecated fromEquirectangularAsync without the explicit init await. Code that ran under older synchronous-init versions.

Related errors

AI-assisted analysis of mrdoob/three.js@da05705fa3 (2026-08-12). Data as JSON: /api/errors/7275ed0817a44aa1. Report an issue: GitHub.