phaserjs/phaser · error · Error

TextureManager.SpriteSheet: Invalid frameWidth given.

Error message

TextureManager.SpriteSheet: Invalid frameWidth given.

What it means

Thrown by the SpriteSheet texture parser when config.frameWidth is null (i.e. not provided). The parser slices a spritesheet into uniform cells, so a frameWidth is mandatory; without it the cut grid is undefined. Note frameHeight defaults to frameWidth, so only frameWidth is checked.

Source

Thrown at src/textures/parsers/SpriteSheet.js:44

 * @param {object} config - An object describing how to parse the Sprite Sheet.
 * @param {number} config.frameWidth - Width in pixels of a single frame in the sprite sheet.
 * @param {number} [config.frameHeight] - Height in pixels of a single frame in the sprite sheet. Defaults to frameWidth if not provided.
 * @param {number} [config.startFrame=0] - The frame to start extracting from. Defaults to zero.
 * @param {number} [config.endFrame=-1] - The frame to finish extracting at. Defaults to -1, which means 'all frames'.
 * @param {number} [config.margin=0] - If the frames have been drawn with a margin, specify the amount here.
 * @param {number} [config.spacing=0] - If the frames have been drawn with spacing between them, specify the amount here.
 *
 * @return {Phaser.Textures.Texture} The Texture modified by this parser.
 */
var SpriteSheet = function (texture, sourceIndex, x, y, width, height, config)
{
    var frameWidth = GetFastValue(config, 'frameWidth', null);
    var frameHeight = GetFastValue(config, 'frameHeight', frameWidth);

    //  If missing we can't proceed
    if (frameWidth === null)
    {
        throw new Error('TextureManager.SpriteSheet: Invalid frameWidth given.');
    }

    //  Add in a __BASE entry (for the entire atlas)
    var source = texture.source[sourceIndex];

    texture.add('__BASE', sourceIndex, 0, 0, source.width, source.height);

    var startFrame = GetFastValue(config, 'startFrame', 0);
    var endFrame = GetFastValue(config, 'endFrame', -1);
    var margin = GetFastValue(config, 'margin', 0);
    var spacing = GetFastValue(config, 'spacing', 0);

    var row = Math.floor((width - margin + spacing) / (frameWidth + spacing));
    var column = Math.floor((height - margin + spacing) / (frameHeight + spacing));
    var total = row * column;

    if (total === 0)
    {

View on GitHub (pinned to 41be1e462b)

Solutions

1. Provide frameWidth (and optionally frameHeight) in the spritesheet config.
2. Double-check the option key spelling (frameWidth, not frameW or width).
3. If the asset is a single image, use this.load.image instead of this.load.spritesheet.
4. For irregular atlases, use this.load.atlas / spritesheet-from-atlas path with the right config.

Example fix

// before
this.load.spritesheet('player', 'img/player.png', {}); // throws

// after
this.load.spritesheet('player', 'img/player.png', { frameWidth: 32, frameHeight: 32 });

function loadSpritesheet(loader, key, url, cfg) {
  if (cfg.frameWidth == null) throw new Error('spritesheet config requires frameWidth');
  loader.spritesheet(key, url, cfg);
}

function hasFrameWidth(cfg) { return cfg != null && cfg.frameWidth != null; }

When it happens

Trigger: Calling loader.spritesheet(key, url, config) with a config missing 'frameWidth'; passing config as the wrong variable or an empty object; a typo like 'frameW' instead of 'frameWidth'.

Common situations: New spritesheet loads where the dev forgot the frameWidth config; copy-paste from a different loader call that used different option names; loading a single image as a spritesheet by mistake.

Related errors

• TextureManager.SpriteSheetFromAtlas: Invalid frameWidth give
• Invalid File type:
• Invalid File key:
• 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/53d82a96ea3ba1ef. Report an issue: GitHub.