phaserjs/phaser · error · Error

URL Error in File:

Error message

URL Error in File: 

What it means

File.js:324 throws when `GetURL(this, this.loader.baseURL)` returns falsy. Per GetURL.js:25, that happens only when `file.url` itself is falsy — i.e. the file's url resolved to an empty string/null/undefined after the constructor's url logic (File.js:78-89) ran. An absolute url is returned as-is, so this guard specifically catches a missing relative url.

Source

Thrown at src/loader/File.js:324

     * @method Phaser.Loader.File#load
     * @since 3.0.0
     */
    load: function ()
    {
        if (this.state === CONST.FILE_POPULATED)
        {
            //  Can happen for example in a JSONFile if they've provided a JSON object instead of a URL
            this.loader.nextFile(this, true);
        }
        else
        {
            this.state = CONST.FILE_LOADING;

            this.src = GetURL(this, this.loader.baseURL);

            if (!this.src)
            {
                throw new Error('URL Error in File: ' + this.key + ' from: ' + this.url);
            }

            if (this.src.indexOf('data:') === 0)
            {
                this.base64 = true;
            }

            this.xhrLoader = XHRLoader(this, this.loader.xhr);
        }
    },

    /**
     * Called when the file finishes loading, is sent a DOM ProgressEvent.
     *
     * @method Phaser.Loader.File#onLoad
     * @since 3.0.0
     *
     * @param {XMLHttpRequest} xhr - The XMLHttpRequest that caused this onload event.

View on GitHub (pinned to 41be1e462b)

Solutions

1. Provide a non-empty `url` (relative or absolute) in the file config, or an `extension` so the url can be auto-built from `path + key + '.' + extension`.
2. If using a prefix/path, ensure `loader.path` + key + extension forms a valid string.
3. Avoid setting `url: null`/`url: ''`; omit the field only when you also supply `extension`.

Example fix

// before
new Phaser.Loader.File({ type: 'image', key: 'hero', url: '' })
// after
new Phaser.Loader.File({ type: 'image', key: 'hero', extension: 'png' }) // url auto-built

const url = fileConfig.url || (fileConfig.key + '.' + (fileConfig.extension || ''))
if (!url) {
  throw new Error('File config needs a url or an extension to build one')
}
const file = new Phaser.Loader.File(fileConfig)

const hasResolvableUrl = (c) => typeof c?.url === 'string' && c.url.length > 0 || (typeof c?.extension === 'string' && c.extension.length > 0)

When it happens

Trigger: Constructing a File with no `url` and no/empty `extension`, so the constructor builds `url = path + key + '.'` only if extension is truthy — if extension defaulted to '' AND url was explicitly set to a falsy value, the resolved url is falsy and GetURL returns false. Also when `url: null` is passed explicitly.

Common situations: Custom File subclasses that compute url conditionally and leave it unset; configs where `url` is conditionally provided by a template that rendered empty; passing `url: ''` thinking the loader will infer a default.

Related errors

• Invalid File type:
• Invalid File key:
• GetCentroid points be a non-empty array
• No cached audio asset with key "
• Audio key "

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/bc5cc4e19106a2f7. Report an issue: GitHub.