phaserjs/phaser · error · Error

Invalid File type:

Error message

Invalid File type: 

What it means

File.js:68 throws when `fileConfig.type` is falsy. The `type` string (image, json, atlas, audio, etc.) sorts the File in the Loader and routes it to the right cache; a missing/empty/false type is treated as invalid because the loader cannot place the file. `GetFastValue` defaults it to `false`, so omitting `type` triggers the guard.

Source

Thrown at src/loader/File.js:68

         *
         * @name Phaser.Loader.File#cache
         * @type {(Phaser.Cache.BaseCache|Phaser.Textures.TextureManager)}
         * @since 3.7.0
         */
        this.cache = GetFastValue(fileConfig, 'cache', false);

        /**
         * The file type string (image, json, etc) for sorting within the Loader.
         *
         * @name Phaser.Loader.File#type
         * @type {string}
         * @since 3.0.0
         */
        this.type = GetFastValue(fileConfig, 'type', false);

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

        /**
         * 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;
        }

View on GitHub (pinned to 41be1e462b)

Solutions

1. Add a valid `type` string to the file config (e.g. `'image'`, `'json'`, `'audio'`, `'xml'`).
2. Prefer the high-level loader APIs (`this.load.image(...)`, `this.load.json(...)`) which set the type internally.
3. When subclassing File, pass a complete config object including `type` to `super(...)`.
4. Validate the config object shape before constructing the File.

Example fix

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

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

const hasValidFileType = (c) => typeof c?.type === 'string' && c.type.length > 0

When it happens

Trigger: Constructing a `new Phaser.Loader.File({ key: 'x', url: 'x.png' })` (or a custom File subclass config) without a `type` field; passing `type: ''` or `type: null`.

Common situations: Writing a custom File type/loader plugin and forgetting to set `type` in the config; building a file config dynamically where a branch leaves `type` unset; copy-pasting a config and dropping the `type` line.

Related errors

• Invalid File key:
• 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/779c85006b8a4d7d. Report an issue: GitHub.