BabylonJS/Babylon.js · error · Error

Image url is not set

Error message

Image url is not set

What it means

EquiRectangularCubeTexture builds a cube texture from an equirectangular (panorama) image URL. The constructor requires a URL because the texture cannot be initialized from nothing; if the url argument is falsy (undefined, null, or empty string), the constructor throws immediately.

Source

Thrown at packages/dev/core/src/Materials/Textures/equiRectangularCubeTexture.pure.ts:69

     * @param onError — defines a callback called if there is an error
     * @param supersample — defines if texture must be supersampled (default: false)
     * @param sphericalPolynomialTargetSize — target face size for spherical polynomial computation. 0 = full resolution (default).
     */
    constructor(
        url: string,
        scene: Scene,
        size: number,
        noMipmap: boolean = false,
        gammaSpace: boolean = true,
        onLoad: Nullable<() => void> = null,
        onError: Nullable<(message?: string, exception?: any) => void> = null,
        supersample = false,
        sphericalPolynomialTargetSize = 0
    ) {
        super(scene);

        if (!url) {
            throw new Error("Image url is not set");
        }

        this._coordinatesMode = Texture.CUBIC_MODE;
        this.name = url;
        this.url = url;
        this._size = size;
        this._supersample = supersample;
        this._noMipmap = noMipmap;
        this.gammaSpace = gammaSpace;
        this._onLoad = onLoad;
        this._onError = onError;
        this._sphericalPolynomialTargetSize = sphericalPolynomialTargetSize;

        this.hasAlpha = false;
        this.isCube = true;

        this._texture = this._getFromCache(url, this._noMipmap, undefined, undefined, undefined, this.isCube);

View on GitHub (pinned to 0592b347b8)

Solutions

1. Ensure the url passed to the constructor is a non-empty string
2. Check the config/env variable feeding the url is actually defined before constructing the texture
3. Fall back to a default HDR asset when the intended url is missing
4. Validate the url with a guard before constructing

Example fix

// before
const envTex = new EquiRectangularCubeTexture(process.env.HDRI_URL, scene, 128);
// after
const hdriUrl = process.env.HDRI_URL;
if (!hdriUrl) throw new Error("HDRI_URL is not configured");
const envTex = new EquiRectangularCubeTexture(hdriUrl, scene, 128);

function buildEnvTexture(url, scene, size) {
  if (typeof url !== "string" || url.length === 0) {
    throw new TypeError("EquiRectangularCubeTexture requires a non-empty url");
  }
  return new EquiRectangularCubeTexture(url, scene, size);
}

function hasUrl(v: unknown): v is string {
  return typeof v === "string" && v.length > 0;
}

let envTex;
try {
  envTex = new EquiRectangularCubeTexture(url, scene, 128);
} catch (e) {
  if (e instanceof Error && e.message === "Image url is not set") {
    console.warn("No HDR url configured; skipping env texture");
  } else throw e;
}

When it happens

Trigger: Calling new EquiRectangularCubeTexture(url, scene, ...) with url undefined, null, or "" — typically because a config value or asset path variable was never set.

Common situations: Environment variables or import.meta.env values not defined (e.g. missing VITE_HDRI_URL), a loader returning undefined for an optional HDR asset, or typos in option keys so the url falls through as undefined.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Layer ${layer} is out of range for a 2D array texture with $
• Sample2DRgbaToRef: widthPx and heightPx must be positive.
• Sample2DRgbaToRef: data length (${data.length}) is less than
• Unable to generateSoloNavMesh: ${result.error}
• Unable to get 2d context

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