phaserjs/phaser · error · Error

Invalid File key:

Error message

Invalid File key: 

What it means

File.js:89 throws when `this.key` is falsy after prefix handling. The key is the unique cache identifier; without it the loaded asset cannot be retrieved. `GetFastValue(fileConfig, 'key', false)` defaults to false, and if a `loader.prefix` is set it is prepended but cannot rescue a false base key.

Source

Thrown at src/loader/File.js:89

        /**
         * Unique cache key (unique within its file type)
         *
         * @name Phaser.Loader.File#key
         * @type {string}
         * @since 3.0.0
         */
        this.key = GetFastValue(fileConfig, 'key', false);

        var loadKey = this.key;

        if (loader.prefix && loader.prefix !== '')
        {
            this.key = loader.prefix + loadKey;
        }

        if (!this.key)
        {
            throw new Error('Invalid File key: ' + this.key);
        }

        var url = GetFastValue(fileConfig, 'url');

        if (url === undefined)
        {
            url = loader.path + loadKey + '.' + GetFastValue(fileConfig, 'extension', '');
        }
        else if (typeof url === 'string' && !url.match(/^(?:blob:|data:|capacitor:\/\/|http:\/\/|https:\/\/|\/\/)/))
        {
            url = loader.path + url;
        }

        /**
         * The URL of the file, not including baseURL.
         *
         * Automatically has Loader.path prepended to it if a string.
         *

View on GitHub (pinned to 41be1e462b)

Solutions

1. Always supply a non-empty, unique `key` in the file config.
2. Use the typed loader methods (`this.load.image(key, url)`) which enforce the key parameter at the API boundary.
3. If building keys dynamically, validate they are non-empty strings before calling load.

Example fix

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

if (!fileConfig.key || typeof fileConfig.key !== 'string') {
  throw new Error('fileConfig.key must be a non-empty string')
}
const file = new Phaser.Loader.File(fileConfig)

const hasValidFileKey = (c) => typeof c?.key === 'string' && c.key.length > 0

When it happens

Trigger: Constructing a File with `new Phaser.Loader.File({ type: 'image' })` (no `key`), or passing `key: ''` / `key: null`. The prefix logic at lines 80-84 only prepends when a base key already exists.

Common situations: Dynamic asset loading where a key variable resolves to undefined (e.g. a loop variable not set); writing a loader plugin that omits the key; refactoring and accidentally deleting the `key` line in a config object.

Related errors

• Invalid File type:
• URL Error in File:
• TextureManager.SpriteSheet: Invalid frameWidth given.
• Must set explicit renderType in custom environment
• Unknown value for renderer type:

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