phaserjs/phaser · error · Error

TextureManager.SpriteSheetFromAtlas: Invalid frameWidth give

Error message

TextureManager.SpriteSheetFromAtlas: Invalid frameWidth given.

What it means

Thrown by SpriteSheetFromAtlas parser when GetFastValue(config, 'frameWidth', null) is falsy. Unlike the plain SpriteSheet parser (which checks === null), this one rejects any falsy value including 0, so a frameWidth of 0 also throws. Used when slicing a single atlas frame into a grid of sub-frames.

Source

Thrown at src/textures/parsers/SpriteSheetFromAtlas.js:40

 * @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] - Index of the start frame in the sprite sheet
 * @param {number} [config.endFrame=-1] - Index of the end frame in the sprite sheet. -1 means all the rest of the 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 SpriteSheetFromAtlas = function (texture, frame, config)
{
    var frameWidth = GetFastValue(config, 'frameWidth', null);
    var frameHeight = GetFastValue(config, 'frameHeight', frameWidth);

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

    //  Add in a __BASE entry (for the entire atlas frame)
    var source = texture.source[0];
    texture.add('__BASE', 0, 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 x = frame.cutX;
    var y = frame.cutY;

    var cutWidth = frame.cutWidth;
    var cutHeight = frame.cutHeight;
    var sheetWidth = frame.realWidth;
    var sheetHeight = frame.realHeight;

View on GitHub (pinned to 41be1e462b)

Solutions

1. Set a positive integer frameWidth in the config.
2. Verify you are using the right parser (atlas spritesheet) vs the plain spritesheet parser.
3. Ensure frameWidth is not 0; pick the actual cell pixel width.
4. Inspect the atlas frame to confirm dimensions are >= frameWidth * columns.

Example fix

// before
this.load.atlas('sheet', 'img/sheet.png', 'img/sheet.json');
TextureManager.SpriteSheetFromAtlas(texture, frame, { frameWidth: 0 }); // throws

// after
TextureManager.SpriteSheetFromAtlas(texture, frame, { frameWidth: 16, frameHeight: 16 });

function parseSSFromAtlas(texture, frame, cfg) {
  if (!cfg || !cfg.frameWidth) throw new Error('SpriteSheetFromAtlas requires a truthy frameWidth');
  // proceed
}

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

When it happens

Trigger: Calling a spritesheet-from-atlas load with config missing frameWidth; passing frameWidth: 0 (treated as missing here); mis-typing the config key.

Common situations: Loading an atlas JSON and then declaring a spritesheet frame inside it without frameWidth; programmatic atlas generation that omits frameWidth; confusion between the two spritesheet parser APIs.

Related errors

• TextureManager.SpriteSheet: Invalid frameWidth given.
• Must set explicit renderType in custom environment
• Unknown value for renderer type:
• No DOM Container set in game config
• Invalid File type:

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