apache/iceberg · error · UncheckedIOException

Failed to write json to file: %s

Error message

Failed to write json to file: %s

What it means

ViewMetadataParser.internalWrite wraps IOExceptions from writing (and JSON-generating) the view metadata to an OutputFile in an UncheckedIOException with this message. It signals the metadata JSON could not be serialized or durably written to the target location.

Source

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

      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. Check storage credentials and permissions for the metadata location
2. Verify network connectivity to the object store/filesystem
3. Confirm the target location is valid and not read-only
4. Retry the commit; transient IO failures usually clear on retry

Example fix

// before
ViewMetadataParser.write(metadata, outputFile);
// after
try {
  ViewMetadataParser.overwrite(metadata, outputFile);
} catch (UncheckedIOException e) {
  LOG.error("Failed writing view metadata to {}", outputFile.location(), e);
  throw e;
}

// verify write access before committing metadata
boolean writable = outputFile.location().startsWith(validMetadataRoot);

try { ViewMetadataParser.overwrite(metadata, outputFile); } catch (UncheckedIOException e) { LOG.error("write failed: {}", outputFile.location(), e); throw e; }

When it happens

Trigger: Writing view metadata to a location without write permission, an unreachable object store, full disk, or when toJson fails due to an unserializable field; gzip output stream errors.

Common situations: Catalogs writing to storage with expired credentials; network partitions to S3/HDFS/GCS during commit; setting an invalid or unwritable write.metadata.path for views.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to read json file: %s
• Failed to write json to file: %s
• Failed to create file: %s
• Failed to close current writer
• Failed to create new data writer

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