What causes "Invalid file format: %s" in apache/iceberg?

Correct the format string to one of the supported enum names: avro, orc, parquet

apache/iceberg · error · IllegalArgumentException

Invalid file format: %s

Error message

Invalid file format: %s

What it means

FileFormat.fromString parses a string like "parquet" or "avro" into the FileFormat enum. It throws IllegalArgumentException when the string is null or does not match any known format name (case-insensitive, via Locale.ROOT upper-casing and valueOf).

Source

Thrown at api/src/main/java/org/apache/iceberg/FileFormat.java:83

    for (FileFormat format : VALUES) {
      int extStart = filename.length() - format.ext.length();
      if (extStart > 0
          && Comparators.charSequences()
                  .compare(format.ext, filename.subSequence(extStart, filename.length()))
              == 0) {
        return format;
      }
    }

    return null;
  }

  public static FileFormat fromString(String fileFormat) {
    Preconditions.checkArgument(null != fileFormat, "Invalid file format: null");
    try {
      return FileFormat.valueOf(fileFormat.toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(String.format("Invalid file format: %s", fileFormat), e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Correct the format string to one of the supported enum names: avro, orc, parquet
Trim/lowercase and validate the configuration value before calling fromString
Catch IllegalArgumentException and fall back to a known-good default format

Example fix

// before
FileFormat fmt = FileFormat.fromString(config.get("format"));
// after
String raw = config.get("format");
if (raw == null || !raw.matches("(?i)avro|orc|parquet")) {
  raw = "parquet";
}
FileFormat fmt = FileFormat.fromString(raw.trim());

Defensive patterns

Strategy: validation

Validate before calling

boolean isValidFormat(String s) {
  return s != null && java.util.Arrays.stream(FileFormat.values())
      .anyMatch(f -> f.name().equalsIgnoreCase(s.trim()));
}

Try / catch

try {
  format = FileFormat.fromString(raw);
} catch (IllegalArgumentException e) {
  format = FileFormat.PARQUET; // default
}

Prevention

Validate format config values against FileFormat.values() at startup
Trim and normalize case before parsing
Use the FileFormat enum constant directly in code instead of strings

When it happens

Trigger: Passing an unrecognized or null format string, e.g. TableProperties default file format set to "orc" in a build without ORC, a typo like "paruqet", or an empty string read from configuration.

Common situations: Typos in write.format.default / spark.sql.iceberg table properties; config files with trailing whitespace or quoted values; using a format module (ORC) that isn't on the classpath so its constant never registered (pre-enum-registration code) or format not part of the enum.

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

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