{"record":{"id":"30a54e61cd41ca93","repo":"kitao/pyxel","slug":"failed-to-read-file-path","errorCode":null,"errorMessage":"Failed to read file '{path}'","messagePattern":"Failed to read file '(.+?)'","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/pyxel-core/src/tmx_parser.rs","lineNumber":57,"sourceCode":"struct TmxMap {\n    #[serde(rename = \"@tilewidth\")]\n    tilewidth: u32,\n    #[serde(rename = \"@tileheight\")]\n    tileheight: u32,\n    #[serde(rename = \"tileset\", default)]\n    tilesets: Vec<Tileset>,\n    #[serde(rename = \"layer\", default)]\n    layers: Vec<Layer>,\n}\n\npub fn parse_tmx(path: &str, layer_index: u32) -> Result<RcTilemap, String> {\n    let err = |msg| format!(\"{msg} '{path}'\");\n\n    // Load and validate the TMX layer.\n    let mut file = File::open(path).map_err(|_| err(\"Failed to open file\"))?;\n    let mut tmx_text = String::new();\n    file.read_to_string(&mut tmx_text)\n        .map_err(|_| err(\"Failed to read file\"))?;\n\n    let tmx: TmxMap = serde_xml_rs::from_str(&tmx_text).map_err(|_| err(\"Failed to parse file\"))?;\n\n    if tmx.tilewidth != TILE_SIZE || tmx.tileheight != TILE_SIZE {\n        return Err(err(\"Invalid tile size in file\"));\n    }\n\n    let tileset = tmx\n        .tilesets\n        .first()\n        .ok_or_else(|| err(\"No tileset found in file\"))?;\n    let columns = tileset\n        .columns\n        .ok_or_else(|| err(\"No embedded tileset in file\"))?;\n\n    let layer = tmx\n        .layers\n        .get(layer_index as usize)","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/kitao/pyxel/blob/50f9bd77780c993aca62b5b221766bde5791081d/crates/pyxel-core/src/tmx_parser.rs#L39-L75","documentation":"`parse_tmx` opened the TMX file but `read_to_string` failed, returning this error. This almost always means the file contains invalid UTF-8 (TMX should be UTF-8 XML) or an I/O error occurred mid-read. The io::Error detail is discarded, only the path is shown.","triggerScenarios":"Calling `parse_tmx(path, layer_index)` on a file that is not valid UTF-8 (e.g. saved as UTF-16 or Latin-1), a corrupted/truncated file, or a transient read error on a network/external drive.","commonSituations":"TMX exported from a tool with a non-UTF-8 encoding; file edited/saved by another program with a different encoding; binary file mistakenly given a .tmx extension; reading from an unstable network mount.","solutions":["Re-export or re-save the TMX file as UTF-8 encoding from Tiled/your editor.","Verify the file is actually XML text, not binary (open in an editor / `file` command).","Re-download or restore the file if corrupted or truncated.","If on a network drive, copy the file locally and retry."],"exampleFix":"// before (file saved as UTF-16)\nlet tilemap = Tilemap::from_tmx(\"level.tmx\", 0)?; // Failed to read file 'level.tmx'\n// after: re-save with encoding=UTF-8 in Tiled preferences, then retry\nlet tilemap = Tilemap::from_tmx(\"level.tmx\", 0)?;","handlingStrategy":"validation","validationCode":"// Verify the file is valid UTF-8 text before parse_tmx\nfn tmx_is_utf8(path: &str) -> Result<(), String> {\n    let bytes = std::fs::read(path).map_err(|e| e.to_string())?;\n    std::str::from_utf8(&bytes)\n        .map(|_| ())\n        .map_err(|_| format!(\"{} is not valid UTF-8; re-save TMX as UTF-8\", path))\n}","typeGuard":null,"tryCatchPattern":"match Tilemap::from_tmx(path, 0) {\n    Ok(tm) => use_tilemap(tm),\n    Err(e) if e.starts_with(\"Failed to read file\") => {\n        eprintln!(\"{} is not valid UTF-8; re-export from Tiled with UTF-8 encoding\", path);\n    }\n    Err(e) => eprintln!(\"TMX load failed: {}\", e),\n}","preventionTips":["Configure Tiled/editor to save maps as UTF-8.","Never rename non-XML/binary files to .tmx.","Verify file integrity (checksums) after download/copy from network storage.","Keep map assets in source control to detect corruption early."],"tags":["rust","io","utf-8","encoding","tmx"],"backgroundTag":"invalid-file-encoding","analyzedSha":"50f9bd77780c993aca62b5b221766bde5791081d","analyzedAt":"2026-09-03T10:27:43.285Z","contentChangedAt":"2026-09-03T10:27:43.285Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}