kitao/pyxel · error

Unsupported encoding in file '{path}'

Error message

Unsupported encoding in file '{path}'

What it means

The layer's tile data is not CSV-encoded. The parser only supports `encoding="csv"`; TMX also allows base64 (optionally zlib/gzip compressed) encodings, which this library cannot decode and rejects explicitly. The message is emitted from the `if layer.data.encoding != "csv"` branch.

Source

Thrown at crates/pyxel-core/src/tmx_parser.rs:78

    if tmx.tilewidth != TILE_SIZE || tmx.tileheight != TILE_SIZE {
        return Err(err("Invalid tile size in file"));
    }

    let tileset = tmx
        .tilesets
        .first()
        .ok_or_else(|| err("No tileset found in file"))?;
    let columns = tileset
        .columns
        .ok_or_else(|| err("No embedded tileset in file"))?;

    let layer = tmx
        .layers
        .get(layer_index as usize)
        .ok_or_else(|| format!("Layer {layer_index} not found in file '{path}'"))?;
    if layer.data.encoding != "csv" {
        return Err(err("Unsupported encoding in file"));
    }

    let tile_ids: Vec<u32> = remove_whitespace(&layer.data.tiles)
        .split(',')
        .map(|s| s.parse::<u32>().map_err(|_| err("Failed to parse file")))
        .collect::<Result<_, _>>()?;

    // Convert TMX global tile IDs into Pyxel image tile coordinates.
    let tilemap = Tilemap::try_new(layer.width, layer.height, ImageSource::Index(0))
        .map_err(|_| err("Layer dimensions are too large in file"))?;
    let mut tilemap_ref = rc_mut!(tilemap);
    for (y, row) in tile_ids.chunks(layer.width as usize).enumerate() {
        for (x, &id) in row.iter().enumerate() {
            let id = (id & !TMX_TILE_FLAG_MASK).saturating_sub(tileset.firstgid);
            tilemap_ref.canvas.write_data(
                x,
                y,
                (

View on GitHub (pinned to 50f9bd7778)

Solutions

1. In Tiled, set Preferences > Editing > Layer Data format to CSV and re-save the map
2. Decode base64 (and decompress zlib/gzip) tile data yourself, then rewrite the layer as CSV before calling parse_tmx
3. Use Tiled to re-export the map with CSV layer data
4. Check the <data encoding="..."> attribute in the TMX and convert non-CSV layers with a script

Example fix

// before
<data encoding="base64" compression="zlib">eJzt...</data>
// after
<data encoding="csv">1,2,3,4,...</data>

fn layer_is_csv(tmx_path: &str) -> std::io::Result<bool> {
    let xml = std::fs::read_to_string(tmx_path)?;
    Ok(xml.contains("encoding=\"csv\""))
}

match parse_tmx(path, layer_index) {
    Ok(tilemap) => tilemap,
    Err(msg) if msg.starts_with("Unsupported encoding") => {
        eprintln!("re-export the map with CSV layer data: {msg}");
        return Err(msg);
    }
    Err(msg) => return Err(msg),
}

When it happens

Trigger: parse_tmx reads a <layer><data> element whose @encoding is anything other than "csv" (e.g. "base64", "base64+zlib", "base64+gzip").

Common situations: Exporting from Tiled with the default base64 encoding; opening a map saved with compression enabled; upgrading a project where the map export settings changed from CSV to base64.

Related errors

• Failed to read file '{path}'
• No tileset found in file '{path}'
• No embedded tileset in file '{path}'
• Failed to open file '{path}'
• Failed to parse file '{path}'

AI-assisted analysis of kitao/pyxel@50f9bd7778 (2026-09-03). Data as JSON: /api/errors/1db486eb69b04d7c. Report an issue: GitHub.