apache/iceberg · error · UncheckedIOException

Failed to read json file: %s

Error message

Failed to read json file: %s

What it means

ViewMetadataParser.read wraps any IOException encountered while opening/reading the view metadata JSON file in an UncheckedIOException with this message. It indicates the view metadata file at the given location could not be read (missing file, permissions, corrupt/gzip stream, malformed JSON).

Source

Thrown at core/src/main/java/org/apache/iceberg/view/ViewMetadataParser.java:183

  public static void overwrite(ViewMetadata metadata, OutputFile outputFile) {
    internalWrite(metadata, outputFile, true);
  }

  public static void write(ViewMetadata metadata, OutputFile outputFile) {
    internalWrite(metadata, outputFile, false);
  }

  public static ViewMetadata read(FileIO io, String path) {
    return read(io.newInputFile(path));
  }

  public static ViewMetadata read(InputFile file) {
    Codec codec = Codec.fromFileName(file.location());
    try (InputStream is =
        codec == Codec.GZIP ? new GZIPInputStream(file.newStream()) : file.newStream()) {
      return fromJson(file.location(), JsonUtil.mapper().readValue(is, JsonNode.class));
    } catch (IOException e) {
      throw new UncheckedIOException(
          String.format("Failed to read json file: %s", file.location()), e);
    }
  }

  private static void internalWrite(
      ViewMetadata metadata, OutputFile outputFile, boolean overwrite) {
    boolean isGzip = Codec.fromFileName(outputFile.location()) == Codec.GZIP;
    OutputStream stream = overwrite ? outputFile.createOrOverwrite() : outputFile.create();
    try (OutputStreamWriter writer =
            new OutputStreamWriter(
                isGzip ? new GZIPOutputStream(stream) : stream, StandardCharsets.UTF_8);
        JsonGenerator generator = JsonUtil.factory().createGenerator(writer)) {
      toJson(metadata, generator);
      generator.flush();
    } catch (IOException e) {
      throw new UncheckedIOException(
          String.format("Failed to write json to file: %s", outputFile.location()), e);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the metadata file location exists and is accessible with the configured FileIO credentials
2. Check whether the file is gzip-compressed consistently with its name/extension
3. Validate the JSON content parses and matches the view metadata schema
4. Re-export or re-create the metadata file if it is corrupt

Example fix

// before
ViewMetadata meta = ViewMetadataParser.read(file);
// after
if (!file.exists()) {
  throw new IllegalArgumentException("Missing view metadata: " + file.location());
}
try {
  ViewMetadata meta = ViewMetadataParser.read(file);
} catch (UncheckedIOException e) {
  throw new IllegalStateException("Corrupt view metadata: " + file.location(), e);
}

try (InputStream in = file.newStream()) { JsonUtil.mapper().readTree(in); } catch (Exception e) { /* location unreadable or invalid */ }

try { ViewMetadataParser.read(file); } catch (UncheckedIOException e) { throw new IllegalStateException("Unreadable view metadata: " + file.location(), e); }

When it happens

Trigger: Calling ViewMetadataParser.read(InputFile) where the file does not exist, is unreadable, gzip decoding fails, or the content is not valid JSON matching the view metadata schema.

Common situations: Registering a view from a wrong/typoed metadata file location; metadata deleted by retention jobs before registration; reading a metadata file across clusters with different credentials; corrupted object storage object.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to write json to file: %s
• Failed to read manifest file: %s
• Failed to read file: %s
• Failed to fetch file: %s
• Unable to read the metrics of the Parquet file:

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/774042759b2dce99. Report an issue: GitHub.