BabylonJS/Babylon.js · error · Error

filename is required when using a URL

Error message

filename is required when using a URL

What it means

LoadWebpImageData supports two input modes: a URL root plus a filename (old API) or a raw Uint8Array of WebP bytes (new API). When given a string URL, it builds image.src as rootUrlOrData + filename; without a filename the resulting URL would be invalid, so it throws immediately. Callers must switch to the Uint8Array form or provide the filename.

Source

Thrown at packages/dev/loaders/src/SPLAT/sog.pure.ts:136

                // Extract pixel data (RGBA per pixel)
                const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
                resolve({ bits: new Uint8Array(imageData.data.buffer), width: imageData.width, height: imageData.height });
            } catch (error) {
                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
                reject(`Error loading image ${image.src} with exception: ${error}`);
            }
        };
        image.onerror = (error) => {
            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
            reject(`Error loading image ${image.src} with exception: ${error}`);
        };

        image.crossOrigin = "anonymous"; // To avoid CORS issues
        let objectUrl: string | undefined;
        if (typeof rootUrlOrData === "string") {
            // old behavior: URL + filename
            if (!filename) {
                throw new Error("filename is required when using a URL");
            }
            image.src = rootUrlOrData + filename;
        } else {
            // new behavior: Uint8Array
            const blob = new Blob([rootUrlOrData as any], { type: "image/webp" });
            objectUrl = URL.createObjectURL(blob);
            image.src = objectUrl;
        }
    });
    return await promise;
}

async function ParseSogDatas(data: SOGRootData, imageDataArrays: IWebPImage[], scene: Scene): Promise<IParsedSplat> {
    const splatCount = data.count ? data.count : data.means.shape[0];
    const rowOutputLength = 3 * 4 + 3 * 4 + 4 + 4; // 32
    const buffer = new ArrayBuffer(rowOutputLength * splatCount);

    const position = new Float32Array(buffer);

View on GitHub (pinned to 0592b347b8)

Solutions

1. Pass the filename argument alongside the root URL: LoadWebpImageData(rootUrl, fileName, engine).
2. Prefer the new API: decode the WebP to a Uint8Array and pass the bytes instead of a URL.
3. If you have a full URL (not root + name), pass an empty-suffix arrangement by giving the complete file name as the second argument.
4. For data URLs, convert to Uint8Array first since the string path always appends filename.

Example fix

// before
LoadWebpImageData("https://cdn.example.com/sog/", undefined, engine); // throws
// after
LoadWebpImageData("https://cdn.example.com/sog/", "means_l.webp", engine);
// or with bytes:
const bytes = new Uint8Array(await fetch(url + "means_l.webp").then(r => r.arrayBuffer()));
LoadWebpImageData(bytes, "", engine);

if (typeof rootUrlOrData === "string" && !filename) {
  throw new Error("Provide a filename when loading SOG images from a root URL");
}

function isByteInput(input: string | Uint8Array, filename?: string): input is Uint8Array {
  return input instanceof Uint8Array || (typeof input === "string" && !!filename);
}

try {
  await loadMeansImageAsync(rootUrl, filename, engine);
} catch (e) {
  if (String(e.message) === "filename is required when using a URL") {
    // switch to bytes path
    const bytes = new Uint8Array(await fetch(rootUrl + "means_l.webp").then(r => r.arrayBuffer()));
    await loadMeansImageAsync(bytes, "", engine);
  } else throw e;
}

When it happens

Trigger: Calling LoadWebpImageData (directly or through SOG parsing paths like loadMeansImageAsync) with a string rootUrl but filename omitted or empty string.

Common situations: Migrating code between API versions where the filename argument was dropped; calling the internal function with just a URL; passing a data URL string while expecting the bytes path.

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

• Cannot load file: a valid scene filename or root url was not
• Failed to create ImageBitmap
• Failed to create canvas
• Failed to get 2D context
• Missing arrays in SOG data.

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