apache/iceberg · error · IllegalArgumentException

Invalid codec name: %s

Error message

Invalid codec name: %s

What it means

TableMetadataParser.Codec.fromName parses a codec name (e.g. "gzip") by uppercasing it and doing an enum valueOf. Any name that isn't a defined Codec constant fails and is rethrown as IllegalArgumentException with 'Invalid codec name'. This validates the write.metadata.previous-versions-max... actually the metadata compression codec configuration before a metadata file is written.

Source

Thrown at core/src/main/java/org/apache/iceberg/TableMetadataParser.java:65

public class TableMetadataParser {

  public enum Codec {
    NONE(""),
    GZIP(".gz");

    private final String extension;

    Codec(String extension) {
      this.extension = extension;
    }

    public static Codec fromName(String codecName) {
      Preconditions.checkArgument(codecName != null, "Codec name is null");
      try {
        return Codec.valueOf(codecName.toUpperCase(Locale.ROOT));
      } catch (IllegalArgumentException e) {
        throw new IllegalArgumentException(String.format("Invalid codec name: %s", codecName), e);
      }
    }

    public static Codec fromFileName(String fileName) {
      Preconditions.checkArgument(
          fileName.contains(".metadata.json"), "%s is not a valid metadata file", fileName);
      // we have to be backward-compatible with .metadata.json.gz files
      if (fileName.endsWith(".metadata.json.gz")) {
        return Codec.GZIP;
      }
      String fileNameWithoutSuffix = fileName.substring(0, fileName.lastIndexOf(".metadata.json"));
      if (fileNameWithoutSuffix.endsWith(Codec.GZIP.extension)) {
        return Codec.GZIP;
      } else {
        return Codec.NONE;
      }
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use an exact supported codec name, e.g. "gzip" or "none", in the configuration
2. Fix the typo by checking the Codec enum's defined constants
3. If you need zstd/snappy metadata compression, upgrade to a version whose Codec enum supports it
4. Pre-validate the configured value against TableMetadataParser.Codec.values() before setting the property

Example fix

// before
props.put("write.metadata.compression-codec", "gz");
// after
props.put("write.metadata.compression-codec", "gzip");

Set<String> allowed = Arrays.stream(TableMetadataParser.Codec.values())
    .map(c -> c.name().toLowerCase(Locale.ROOT))
    .collect(Collectors.toSet());
if (!allowed.contains(configuredCodec.toLowerCase(Locale.ROOT))) {
  throw new IllegalArgumentException("Codec must be one of " + allowed);
}

try { TableMetadataParser.Codec.fromName(name); }
catch (IllegalArgumentException e) {
  LOG.error("Bad write.metadata.compression-codec '{}'; use gzip or none", name);
}

When it happens

Trigger: Calling TableMetadataParser.Codec.fromName("GZIP") with a typo'd or unsupported string, e.g. table property write.metadata.compression-codec set to "gz", "zip", or "zstd" when only NONE/GZIP (or the supported set) exists.

Common situations: Config typo in the metadata compression codec property; copying a config from another system (parquet/orc codec names like snappy, zstd) that the metadata codec enum doesn't support; case-sensitive assumptions resolved by the toUpperCase, but abbreviations still fail.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid distribution mode: %s
• Invalid file format: %s
• Invalid rewrite job order name: %s
• String.format("Invalid snapshot ref type: %s", snapshotRefTy
• Cannot support given S3 encryption type:

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