apache/seatunnel · error · IllegalArgumentException

Excel file must have a .gz extension. File: %s

Error message

Excel file must have a .gz extension. File: %s

What it means

In AbstractReadStrategy.resolveArchiveCompressedInputStream, EXCEL files inside a .gz-compressed archive must keep a .gz extension so the reader can recover the full compressed file name (the .gz suffix is stripped to get the Excel file name). If an Excel path lacks the .gz extension, IllegalArgumentException 'Excel file must have a .gz extension' is thrown (AbstractReadStrategy.java:518).

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/reader/AbstractReadStrategy.java:518

                                    partitionsMap,
                                    entry.getName());
                        }
                    }
                }
                break;
            case GZ:
                try (GzipCompressorInputStream gzipIn =
                        new GzipCompressorInputStream(hadoopFileSystemProxy.getInputStream(path))) {
                    GzipParameters parameters = gzipIn.getMetaData();
                    String fileName = parameters.getFilename();
                    if (fileName == null) {
                        // remove file suffix
                        // eg: excel need full compressed name
                        if (fileFormat == FileFormat.EXCEL) {
                            if (path.endsWith(".gz")) {
                                fileName = path.substring(0, path.length() - 3);
                            } else {
                                throw new IllegalArgumentException(
                                        "Excel file must have a .gz extension. File: " + path);
                            }
                        } else {
                            fileName = path;
                        }
                    }
                    readProcess(
                            split,
                            output,
                            copyInputStream(gzipIn, effectiveMaxBytes),
                            partitionsMap,
                            fileName);
                }
                break;
            case NONE:
                readProcess(
                        split,
                        output,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Rename the file so it ends with .gz (e.g. report.xlsx.gz) and re-run.
2. If the file is not actually gzipped, disable compress_codec or use the matching compress option.
3. For non-gzip archives, use a format other than EXCEL or a supported archive layout.
4. Verify with `file report.xlsx.gz` that the artifact is really gzip data.

Example fix

// before
# file: report.xlsx (gzipped, renamed)
// after
mv report.xlsx report.xlsx.gz

if ("excel".equals(fileFormatType) && compressCodecIsGzip && !entryPath.endsWith(".gz")) {
    throw new IllegalArgumentException("Excel + gzip requires .gz extension: " + entryPath);
}

try {
    // read archive
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains(".gz extension")) {
        throw new IllegalStateException("Rename the Excel archive to end with .gz", e);
    }
    throw e;
}

When it happens

Trigger: Reading an EXCEL-format source whose compressed/archive entry path does not end with '.gz' — e.g. the file was gzipped but saved as .xlsx.gz.txt, renamed to drop .gz, or compressed with a different extension.

Common situations: Renaming gzip files during upload; upload pipelines stripping double extensions; users zipping Excel files as .zip/.bz2 and expecting Excel+gzip special-casing to apply; automation that munges file names.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION
• The file does not support the compressed file reading
• The {} file format is incorrect. Please check the format in
• enable_file_split=true but compress_codec={} or archive_comp
• prepare method is not supported

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/582f33548bce2817. Report an issue: GitHub.