Common Issues

Tilesets

“Image dimensions must be multiples of the tile size”

The image does not align with the current project tile size.

That means both the image width and height must be multiples of the current tile size.

Examples:

• 16px tile size: 256 x 256 tileset works
• 16px tile size: 250 x 256 tileset does not work
• 8px tile size: 160 x 80 tileset works

Fix:

• Confirm the project tile size
• Resize the tileset image
• Import it again

“Please select an image file”

You tried to update a tileset with a file that is not an image.

Fix:

• Use a valid image file
• Prefer PNG for pixel art

“Tileset dimensions must match”

You are updating an existing tileset with an image that has a different width or height.

The new image must:

• Have the exact same width as the current image
• Have the exact same height as the current image
• Still be compatible with the project tile size

Fix:

• Export or inspect the current tileset dimensions
• Resize the replacement image to the same dimensions
• Update the tileset again

“Can't remove this spritesheet: used in the map”

Sprite Fusion blocks removal while the tileset is still used by any layer in the map editor.

Before removing it:

• Erase tiles using that tileset
• Check hidden layers too
• Remove the tileset again

“Tileset already loaded”

The same autotile tileset package is already loaded in the project.

Fix:

• Use the existing loaded tileset
• Remove the existing one first if you need to re-import it

“This is not a valid tileset”

The file is not a regular image and is not a recognized autotile package.

Fix:

• Import an image for a regular tileset
• Import a supported autotile package JSON for autotiles

“Resource source not recognized” or “Uploaded tileset not recognized”

The autotile package comes from an unsupported provider or unsupported package layout.

Currently recognized providers:

• retrodiffusion
• pixellab

Fix:

• Export the package again from a supported provider
• Import the original package JSON, not a modified version

“Invalid autotile tileset dimensions”

The autotile package image does not match the project tile size or expected autotile layout.

Fix:

• Check the project tile size
• Import the package into a compatible project
• Re-export the autotile package from its source tool if needed

Project Files

“Invalid map”

The loaded file is not a valid Sprite Fusion project file.

Fix:

• Load a project JSON exported from Sprite Fusion
• Do not load map exports like map.json, map.tmx, or scene.png as project files

See Project Import/Export.

“Invalid preset”

The loaded autotile preset does not match the expected preset format.

Fix:

• Load a preset JSON saved from Sprite Fusion
• Do not load a full project JSON as an autotile preset

“Auto-save failed :(”

Sprite Fusion could not write the local autosave.

Fix:

• Export a project JSON manually
• Refresh the editor
• Check browser storage if the issue keeps happening

Project Settings

“Please remove all tiles before changing the tile size”

Sprite Fusion blocks tile-size changes once tiles have been placed.

Fix:

• Set the tile size at the beginning of a project
• If you must change it, clear the existing map tiles first
• Change the tile size
• Import tilesets again if needed

“Please disable the GB Studio mode”

GB Studio mode locks the tile size to 8x8.

Fix:

• Disable GB Studio Mode
• Change the tile size

Attributes

“This export doesn't support per-tile instance attributes”

You enabled per-tile instance attributes and chose an export target that only supports per-tile attributes.

Fix:

• Disable per-tile instance attributes in project settings
• Move your attributes to the tileset tile definition
• Export again

See Tile Attributes.

“Map tiles attributes must match ones set on the spritesheet”

You are exporting to a strict engine format while placed tiles contain attributes that do not match the underlying tileset tile attributes.

Fix:

• Open the tileset tile with Attributes
• Define the expected attributes there
• Remove placement-only mismatches
• Export again

“Some tiles have duplicate attributes keys”

A tile contains repeated attribute keys.

Attribute keys must be unique on the same tile.

Fix:

• Open the tile with Attributes
• Remove duplicate keys
• Export again

Exporting

“The map is too large to export!”

The browser export request is too large for packaged exports.

Fix:

• Reduce the map size
• Reduce the visible export scope
• Remove unused tiles or layers
• Export from the desktop version for larger projects

“Could not export” or “export failed”

The selected export failed before the file could be created.

Fix:

• Check the more specific error shown before it
• Make sure the map has the required tilesets and layers
• Try again from the desktop version if the browser export keeps failing

GB Studio Export

GB Studio export has strict limits.

See GB Studio Mode for the full setup.

“GBStudio only supports 8x8 tiles”

Fix:

• Enable GB Studio mode
• Or set the project tile size to 8x8 before drawing

“GBStudio only supports 192 unique tiles”

Fix:

• Reduce the number of unique tiles used in the map
• Reuse existing tiles where possible
• Watch the unique tile counter in GB Studio mode

“GBStudio only supports maps of 160x144 minimum”

Fix:

• Make the visible map at least 160 x 144
• Use the minimum-size overlay in GB Studio mode

“GBStudio only supports maps of 2040px side maximum”

Fix:

• Reduce the map width or height
• Split the scene into smaller GB Studio scenes

“GBStudio only supports maps of 1048320px maximum”

Fix:

• Reduce the total map area
• Split the scene into smaller GB Studio scenes

Get the Desktop Version

• Works 100% offline
• Faster map exports
• One-time purchase
• Lifetime updates included

Get the Desktop version