apache/iceberg · error · IllegalArgumentException

Unsupported Parquet page version

Error message

Unsupported Parquet page version: %s (must be v1 or v2)

What it means

Parquet.Context.toWriterVersion converts the configured Parquet page format version string to a parquet WriterVersion; unparseable values raise this IllegalArgumentException. Only v1/v2 page formats are accepted.

Solutions

1. Set the page version to 'v1' or 'v2' exactly
2. Check the property value for stray characters/casing
3. Remove the property to use the library default

Example fix

// before
spark.conf.set("write.parquet.page-version", "2")
// after
spark.conf.set("write.parquet.page-version", "v2")

String pageVersion = props.getProperty("write.parquet.page-version");
if (pageVersion != null) {
  Preconditions.checkArgument(pageVersion.equals("v1") || pageVersion.equals("v2"), "Unsupported Parquet page version: %s (must be v1 or v2)", pageVersion);
}

try {
  newContext();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Unsupported Parquet page version")) { /* fix property to v1 or v2 */ }
  else throw e;
}

When it happens

Trigger: Setting write.parquet.page-version (Parquet.PARQUET_PAGE_VERSION) to a string other than what WriterVersion.fromString accepts, e.g. 'v3' or 'parquet1'.

Common situations: Typos in table/Spark config ('2' vs 'v2'); copying configs from other engines that use different naming for page versions.

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

• Class was not found
• Fallback ID assignment in Parquet is UNSAFE and will be…
• Skipping bloom filter config for missing field
• Skipping column statistics config for missing field
• Skipping dictionary encoding config for missing field

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/Parquet.java:802

            ImmutableMap.of(),
            dictionaryEnabled,
            ImmutableMap.of(),
            dataContext.trackUncompressedRowGroupSize());
      }

      private static CompressionCodecName toCodec(String codecAsString) {
        try {
          return CompressionCodecName.valueOf(codecAsString.toUpperCase(Locale.ROOT));
        } catch (IllegalArgumentException e) {
          throw new IllegalArgumentException("Unsupported compression codec: " + codecAsString);
        }
      }

      private static WriterVersion toWriterVersion(String pageVersion) {
        try {
          return WriterVersion.fromString(pageVersion);
        } catch (IllegalArgumentException e) {
          throw new IllegalArgumentException(
              "Unsupported Parquet page version: " + pageVersion + " (must be v1 or v2)");
        }
      }

      int rowGroupSize() {
        return rowGroupSize;
      }

      int pageSize() {
        return pageSize;
      }

      int pageRowLimit() {
        return pageRowLimit;
      }

      int dictionaryPageSize() {
        return dictionaryPageSize;

View on GitHub (pinned to 86d9c8fc54)