apache/iceberg · error · UnsupportedOperationException

Cannot write using unregistered internal data format

Error message

Cannot write using unregistered internal data format: %s

What it means

InternalData.write() only supports file formats that have a WriteBuilder registered (e.g., Avro, Parquet, ORC registered statically). Requesting a write with any other FileFormat throws UnsupportedOperationException because no internal writer implementation exists for it.

Solutions

1. Use a registered format such as FileFormat.AVRO, FileFormat.PARQUET, or FileFormat.ORC for internal data writes
2. Register a custom WriteBuilder via InternalData's registration mechanism if extending
3. Check the FileFormat value passed in — it likely comes from misparsed configuration

Example fix

// before
InternalData.write(FileFormat.fromString("data"), out)...
// after
InternalData.write(FileFormat.AVRO, out)...

if (format != FileFormat.AVRO && format != FileFormat.PARQUET && format != FileFormat.ORC) {
  throw new IllegalArgumentException("Unsupported internal format: " + format);
}

try {
  InternalData.write(format, file)...;
} catch (UnsupportedOperationException e) {
  LOG.error("Internal write unsupported for {}", format, e);
}

When it happens

Trigger: Calling InternalData.write(FileFormat.X, outputFile) where X is a format not registered in WRITE_BUILDERS — e.g., a hypothetical/unknown format, or a format supported only for reading (metadata/position-delete contexts).

Common situations: Passing a user-configured file format string into InternalData for internal metadata files; adding a new FileFormat enum without registering a builder; tests using a custom format.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot read using unregistered internal data format
• Backup table name cannot be specified
• Batch reading is not supported in non-vectorized reader
• Bucket transform is not supported
• Can't modify an empty struct

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/InternalData.java:91

      DynMethods.builder("register").impl(classToRegister).buildStaticChecked().invoke();
    } catch (NoSuchMethodException | NoClassDefFoundError | ExceptionInInitializerError e) {
      // failing to load an optional format is normal and does not require a stack trace
      Throwable cause = e.getCause() != null ? e.getCause() : e;
      LOG.info("Cannot register {} for metadata files: {}", classToRegister, cause.toString());
    }
  }

  static {
    registerSupportedFormats();
  }

  public static WriteBuilder write(FileFormat format, OutputFile file) {
    Function<OutputFile, WriteBuilder> writeBuilder = WRITE_BUILDERS.get(format);
    if (writeBuilder != null) {
      return writeBuilder.apply(file);
    }

    throw new UnsupportedOperationException(
        "Cannot write using unregistered internal data format: " + format);
  }

  public static ReadBuilder read(FileFormat format, InputFile file) {
    Function<InputFile, ReadBuilder> readBuilder = READ_BUILDERS.get(format);
    if (readBuilder != null) {
      return readBuilder.apply(file);
    }

    throw new UnsupportedOperationException(
        "Cannot read using unregistered internal data format: " + format);
  }

  public interface WriteBuilder {
    /** Set the file schema. */
    WriteBuilder schema(Schema schema);

    /** Set the file schema's root name. */

View on GitHub (pinned to 86d9c8fc54)