{"record":{"id":"ffac3a4269b4ef68","repo":"apache/iceberg","slug":"failed-to-read-metadata-for-file-s","errorCode":null,"errorMessage":"Failed to read metadata for file: %s","messagePattern":"Failed to read metadata for file: (.+?)","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/avro/AvroIterable.java","lineNumber":70,"sourceCode":"    this.reuseContainers = reuseContainers;\n  }\n\n  private DataFileReader<D> initMetadata(DataFileReader<D> metadataReader) {\n    if (metadata == null) {\n      this.metadata = Maps.newHashMap();\n      for (String key : metadataReader.getMetaKeys()) {\n        metadata.put(key, metadataReader.getMetaString(key));\n      }\n    }\n    return metadataReader;\n  }\n\n  public Map<String, String> getMetadata() {\n    if (metadata == null) {\n      try (DataFileReader<D> reader = newFileReader()) {\n        initMetadata(reader);\n      } catch (IOException e) {\n        throw new RuntimeIOException(e, \"Failed to read metadata for file: %s\", file.location());\n      }\n    }\n    return metadata;\n  }\n\n  @Override\n  public CloseableIterator<D> iterator() {\n    FileReader<D> fileReader = initMetadata(newFileReader());\n\n    if (start != null) {\n      if (reader instanceof SupportsRowPosition) {\n        ((SupportsRowPosition) reader)\n            .setRowPositionSupplier(\n                Suppliers.memoize(() -> AvroIO.findStartingRowPos(file::newStream, start)));\n      }\n      fileReader = new AvroRangeIterator<>(fileReader, start, end);\n    } else if (reader instanceof SupportsRowPosition) {\n      ((SupportsRowPosition) reader).setRowPositionSupplier(() -> 0L);","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/avro/AvroIterable.java#L52-L88","documentation":"AvroIterable.getMetadata lazily opens the Avro file solely to read the footer/metadata map. If opening or reading the footer raises an IOException (the file is missing, truncated, or not a valid Avro container), the exception is wrapped in a RuntimeIOException that includes the file location.","triggerScenarios":"Calling AvroIterable.getMetadata() (or any access path that initializes metadata) when the file at file.location() cannot be opened or its Avro footer cannot be parsed: key-decompression mismatch, wrong codec, zero-byte file, or deleted object.","commonSituations":"Pointing a reader at a file deleted by a concurrent compaction/expiry; uploading an incomplete file; trying to read an Orc/Parquet file with the Avro reader by mistake; permissions blocking the read on HDFS/S3.","solutions":["Check the file exists and is readable at the given location (list/stat via FileIO)","Confirm the file is actually an Avro container and the read uses the matching Avro init/model (e.g. GenericAvroReader) and compression codec is on the classpath (zstd/bzip2/snappy)","Re-resolve the path from current table metadata in case the file was replaced or deleted","Fix storage credentials/permissions so the reader can open the object"],"exampleFix":"// before: hardcoded stale path\nAvroIterable<Record> it = Avro.read(io().newInputFile(\"s3://bucket/old/part-0000.avro\")).build();\nMap<String,String> meta = it.getMetadata();\n// after: resolve from current manifest entry\nDataFile df = currentManifestRow(dataFilePath);\nAvroIterable<Record> it = Avro.read(io().newInputFile(df.location())).build();\nMap<String,String> meta = it.getMetadata();","handlingStrategy":"try-catch","validationCode":"boolean readable = fileIO.exists(location) && fileIO.newInputFile(location).getLength() > 0;\nif (!readable) throw new IllegalStateException(\"File missing or empty: \" + location);","typeGuard":null,"tryCatchPattern":"try (AvroIterable<D> it = Avro.read(in).project(schema).build()) {\n  Map<String,String> meta = it.getMetadata();\n} catch (RuntimeIOException e) {\n  LOG.error(\"Cannot read Avro metadata for {}\", location, e);\n  throw new UncheckedIOException(e);\n}","preventionTips":["Ensure compression codec libraries (snappy/zstd/bzip2) are on the runtime classpath","Validate storage credentials before starting jobs","Never assume a file persists after expiry/compaction — resolve paths from current metadata","Check magic bytes if consuming third-party files"],"tags":["avro","metadata","io"],"backgroundTag":"file-open-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}