apache/iceberg · error · IllegalArgumentException

Cannot serialize FileIO

Error message

Cannot serialize FileIO: <impl> does not expose configuration properties

What it means

FileIOParser.toJson requires the FileIO to expose its configuration via properties(). FileIO implementations that do not support properties (they throw UnsupportedOperationException) cannot be serialized to JSON, so a descriptive IllegalArgumentException names the offending implementation class.

Solutions

1. Implement properties() in the custom FileIO to return its configuration map.
2. Serialize the correct concrete FileIO (e.g. HadoopFileIO / S3FileIO) rather than a wrapper.
3. If wrapping a FileIO, delegate properties() to the underlying implementation.
4. Use FileIOUtil or the io() instance from the table/catalog, which is guaranteed serializable.

Example fix

// before
class MyFileIO implements FileIO {
  // no properties() override -> UnsupportedOperationException
}
// after
class MyFileIO implements FileIO {
  private final Map<String, String> props;
  @Override
  public Map<String, String> properties() { return props; }
}

Map<String, String> props;
try { props = io.properties(); } catch (UnsupportedOperationException u) {
  throw new IllegalArgumentException("FileIO " + io.getClass().getName() + " not serializable");
}

static boolean jsonSerializable(FileIO io) {
  try { return io.properties() != null; }
  catch (UnsupportedOperationException e) { return false; }
}

try {
  FileIOParser.toJson(io, generator);
} catch (IllegalArgumentException e) {
  LOG.error("FileIO {} cannot be serialized: {}", io.getClass().getName(), e.getMessage());
  throw e;
}

When it happens

Trigger: Calling FileIOParser.toJson(io, generator) (directly or via table metadata / parse of a FileIO that must round-trip) with a FileIO whose properties() throws UnsupportedOperationException, e.g. a custom or minimal FileIO implementation.

Common situations: Custom FileIO implementations that don't override properties(); passing a mock or anonymous FileIO into serialization; serializing a table whose io object is not the real catalog-backed implementation.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Cannot serialize an eager input file
• Cannot serialize type: + typeId
• Cannot write unsupported term
• does not have a format version
• does not have a metadata file location

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/io/FileIOParser.java:49

  private static final String FILE_IO_IMPL = "io-impl";
  private static final String PROPERTIES = "properties";

  public static String toJson(FileIO io) {
    return toJson(io, false);
  }

  public static String toJson(FileIO io, boolean pretty) {
    return JsonUtil.generate(gen -> toJson(io, gen), pretty);
  }

  public static void toJson(FileIO io, JsonGenerator generator) throws IOException {
    String impl = io.getClass().getName();
    Map<String, String> properties;
    try {
      properties = io.properties();
    } catch (UnsupportedOperationException e) {
      throw new IllegalArgumentException(
          String.format(
              "Cannot serialize FileIO: %s does not expose configuration properties", impl));
    }

    Preconditions.checkArgument(
        properties != null,
        "Cannot serialize FileIO: invalid configuration properties (null)",
        impl);

    generator.writeStartObject();

    generator.writeStringField(FILE_IO_IMPL, impl);
    JsonUtil.writeStringMap(PROPERTIES, properties, generator);

    generator.writeEndObject();
  }

  public static FileIO fromJson(String json) {

View on GitHub (pinned to 86d9c8fc54)