{"record":{"id":"741d44405271ae25","repo":"apache/iceberg","slug":"failed-to-read-file-s-741d44","errorCode":null,"errorMessage":"Failed to read file: %s","messagePattern":"Failed to read file: (.+?)","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/TableMetadataParser.java","lineNumber":305,"sourceCode":"    generator.writeObjectFieldStart(REFS);\n    for (Map.Entry<String, SnapshotRef> refEntry : refs.entrySet()) {\n      generator.writeFieldName(refEntry.getKey());\n      SnapshotRefParser.toJson(refEntry.getValue(), generator);\n    }\n    generator.writeEndObject();\n  }\n\n  public static TableMetadata read(FileIO io, String path) {\n    return read(io.newInputFile(path));\n  }\n\n  public static TableMetadata read(InputFile file) {\n    Codec codec = Codec.fromFileName(file.location());\n    try (InputStream is =\n        codec == Codec.GZIP ? new GZIPInputStream(file.newStream()) : file.newStream()) {\n      return fromJson(file, JsonUtil.mapper().readValue(is, JsonNode.class));\n    } catch (IOException e) {\n      throw new RuntimeIOException(e, \"Failed to read file: %s\", file.location());\n    }\n  }\n\n  /**\n   * Read TableMetadata from a JSON string.\n   *\n   * <p>The TableMetadata's metadata file location will be unset.\n   *\n   * @param json a JSON string of table metadata\n   * @return a TableMetadata object\n   */\n  public static TableMetadata fromJson(String json) {\n    return fromJson(null, json);\n  }\n\n  /**\n   * Read TableMetadata from a JSON string.\n   *","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/TableMetadataParser.java#L287-L323","documentation":"read() opens a metadata JSON file (auto-detecting gzip by the .gz/.metadata.json.gz filename), parses it with Jackson, and builds TableMetadata. Any IOException reading or decompressing the file becomes RuntimeIOException 'Failed to read file: <location>'. It means the metadata file itself could not be read or decompressed.","triggerScenarios":"TableMetadataParser.read(InputFile) on a metadata file that is missing or truncated, unreadable (permissions), or corrupt gzip stream (e.g. a .metadata.json.gz file that is not actually gzipped); FileIO.newStream() throwing IOException.","commonSituations":"Stale/invalid table metadata location after manual catalog edits or bucket recreation; partial upload of metadata files; pointing a static table at a deleted or moved metadata file; decompressing a file saved without gzip despite the .gz name.","solutions":["Confirm the metadata file exists and is readable at file.location() via the catalog","If the file is corrupt, roll back the catalog pointer to a valid earlier metadata version","Check that gzip naming matches actual content: only .metadata.json.gz files are gzip-decoded","Inspect the chained cause (e.g. FileNotFoundException, permission error) and fix storage access"],"exampleFix":"// before\nTableMetadata meta = TableMetadataParser.read(fileIO.newInputFile(oldLoc)); // file moved\n// after\nString loc = table.operations().current().metadataFileLocation();\nTableMetadata meta = TableMetadataParser.read(fileIO.newInputFile(loc));","handlingStrategy":"try-catch","validationCode":"InputFile f = fileIO.newInputFile(loc);\nif (!f.exists()) { throw new FileNotFoundException(\"Metadata file missing: \" + loc); }","typeGuard":null,"tryCatchPattern":"try { return TableMetadataParser.read(file); }\ncatch (RuntimeIOException e) {\n  throw new IllegalStateException(\"Unreadable metadata \" + file.location()\n      + \"; cause: \" + e.getCause(), e);\n}","preventionTips":["Resolve the metadata path from the catalog pointer, not cached/stale strings","Verify .gz naming matches actual gzip content before reading","Keep multiple metadata versions and roll back the pointer if one is corrupt","Check bucket/object existence after storage lifecycle or migration operations"],"tags":["io","file-read","metadata","gzip","iceberg"],"backgroundTag":"file-read-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}