Diagnose a conversion problem by its symptom

Start with the visible symptom, then check the source contract for the selected mode. The converter rejects malformed or ambiguous input instead of guessing missing data, so the first diagnostic often points to the boundary that protects the output.

The Convert button is unavailable

Likely cause: the selected file set is incomplete or the spritesheet grid is not ready. PNG + JSON needs both matching files; most project and animation modes need exactly one file; grid mode additionally needs a positive exact-fit configuration.

Practical fix: choose the mode first, clear unrelated files, select the required set again, and review the status beside the controls. In grid mode, wait for the local dimension preview and make the overlay cover the image exactly. See the format chooser.

Invalid or unsupported file type

Likely cause: the extension is not accepted for the mode, or the bytes do not match the claimed format. Renaming a JPEG to .png does not add a PNG signature.

Validation: flat image importers check signatures; project readers validate their JSON, ZIP, or binary container identity before mapping artwork.

Practical fix: reopen the source in the program that created it and save or export a fresh file in the documented format.

PNG sequence dimensions do not match

Likely cause: at least one decoded frame has a different canvas width or height from the first file.

Validation: the importer reports the one-based frame number and both dimensions; it does not scale or crop.

Practical fix: resize the canvas or add transparent padding so all frames share one size, then check their supplied order. Follow the PNG sequence preparation steps.

The spritesheet grid does not fit

Likely cause: frame width times columns or frame height times rows differs from the PNG dimensions. Margins, separators, or uneven cells are common causes.

Validation: all four settings must be positive integers and the grid product must equal the decoded image exactly.

Practical fix: crop extra borders, enter the correct divisors, or use matching atlas JSON for packed rectangles. See grid and atlas examples.

Spritesheet metadata is malformed

Likely cause: a frame rectangle is invalid or outside the PNG, durations are not positive, trimming metadata is incomplete, the rotation value or convention is unsupported, or the JSON uses another schema.

Validation: the importer accepts only supported root-level frame layouts and validates every rectangle before building a project.

Practical fix: pair the JSON with the image from the same export. Re-export rather than editing coordinates blindly. If a clean frame sequence is available, use it as a fallback.

A project file is rejected

Likely cause: its version or structure differs from the tested subset, required layer data is absent, the archive is unsafe or malformed, or editor-only features are present.

Validation: project importers check identity, versions, dimensions, resource limits, required entries, layer coverage, and pixel payloads. A valid file can still be unsupported.

Practical fix: make a simplified copy in the source editor, keep supported raster layers, and remove only features you can safely rasterize. Use the specific Pixilart, Piskel, or raster project guide.

Unsupported layer type or blend mode

Likely cause: the source contains a group, vector layer, tilemap, text object, smart object, mask, effect, adjustment, clipping behavior, or non-normal blend.

Validation: these are rejected instead of flattened and mislabeled as preserved editor layers.

Practical fix: retain the original, then create a separate simplified raster copy. If editability is not required, export rendered frames and use PNG sequence, spritesheet, GIF, or APNG mode.

GIF or APNG is reported as unsupported

Likely cause: the file uses valid animation features outside the narrow decoder subset, is a static PNG selected in APNG mode, or has malformed timing, bounds, sequence, CRC, palette, filter, compression, or disposal data.

Practical fix: re-export a non-interlaced animation using ordinary supported settings, or export a PNG sequence. Compare GIF and APNG behavior in the animation guide.

The output opens but looks wrong

Compare the in-page preview and Aseprite result in this order: canvas size, frame count, frame order, frame duration, transparency, cel offset, layer order, visibility, and opacity. For GIF/APNG, inspect the frame after a partial rectangle or disposal operation. For trimmed atlases, inspect placement at the canvas edges.

If the output has one layer from PNG, spritesheet, GIF, or APNG, that is expected. Those flat sources cannot recover original editor layers. If Aseprite itself reports an open error, record the exact Aseprite version and message and keep the generated file for a minimal report.

Very large files, a frozen tab, or browser reload

Likely cause: decoded RGBA pixels and intermediate copies exceed practical memory even though the compressed file is small. Cost grows with canvas area, frames, layers, previews, and output bytes.

Practical fix: close memory-heavy tabs, use an up-to-date 64-bit desktop browser, reduce empty canvas, split long animations, or reduce layer count. The app intentionally has no remote fallback for oversized artwork. Read the memory and privacy architecture.

The download does not start

Check the browser downloads list, allow generated downloads for the site, and disable an extension that blocks Blob URLs. Changing mode or clearing selected files invalidates the previous conversion result, so convert again before downloading. Do not upload private artwork to another service just to work around a local download restriction.

Report a problem without exposing artwork

Create the smallest new synthetic file that demonstrates the issue. Include the import mode, browser, operating system, Aseprite version, exact safe diagnostic, source dimensions, and expected frame/layer behavior. Attaching anything to GitHub is an external sharing action and is not part of the local conversion privacy boundary.