apache/seatunnel · error · java.lang.IllegalArgumentException

Operator %s requires a compareOption (cross-field comparison

Error message

Operator %s requires a compareOption (cross-field comparison), but compareOption is null

What it means

ExcelReadStrategy.setCatalogTable extracts the SeaTunnelRowType from the provided CatalogTable and requires non-empty fieldNames and fieldTypes; the Excel reader cannot infer a schema by itself. If either array is null or empty it throws FileConnectorException with UNSUPPORTED_OPERATION, because subsequent row construction depends entirely on the user-declared schema.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/configuration/util/Condition.java:61

    Condition(
            Option<T> option, ConditionOperator operator, T expectValue, Option<?> compareOption) {
        this(option, operator, expectValue, compareOption, null);
    }

    Condition(
            Option<T> option,
            ConditionOperator operator,
            T expectValue,
            Option<?> compareOption,
            ConditionExtension<T> extension) {
        if (option == null) {
            throw new IllegalArgumentException("Condition option must not be null");
        }
        if (operator == null) {
            throw new IllegalArgumentException("Condition operator must not be null");
        }
        if (operator.getSource() == ConditionOperator.Source.FIELD && compareOption == null) {
            throw new IllegalArgumentException(
                    String.format(
                            "Operator %s requires a compareOption (cross-field comparison), but compareOption is null",
                            operator.name()));
        }
        if (operator.getArity() == ConditionOperator.Arity.BINARY
                && operator.getSource() == ConditionOperator.Source.LITERAL
                && expectValue == null) {
            throw new IllegalArgumentException(
                    String.format(
                            "Operator %s requires an expectValue, but expectValue is null",
                            operator.name()));
        }
        if (operator == ConditionOperator.EXTENSION && extension == null) {
            throw new IllegalArgumentException(
                    "Operator EXTENSION requires a non-null ConditionExtension");
        }
        this.option = option;
        this.operator = operator;

View on GitHub (pinned to cf67b549a7)

Solutions

Define schema in the source config so the CatalogTable carries field names and types (schema block in the Excel source configuration).
When constructing CatalogTable programmatically, populate SeaTunnelRowType with matching, non-empty fieldNames and fieldTypes arrays of equal length.
Verify the upstream component that produces the CatalogTable actually resolves the table schema before calling setCatalogTable.

Example fix

// before
SeaTunnelRowType rowType = new SeaTunnelRowType(new String[]{}, new SeaTunnelType[]{}, new int[]{});
// after
SeaTunnelRowType rowType = new SeaTunnelRowType(
    new String[]{"name", "age"},
    new SeaTunnelType[]{BasicType.STRING_TYPE, BasicType.INT_TYPE},
    new int[]{0, 1});

Defensive patterns

Strategy: validation

Validate before calling

java
SeaTunnelRowType rowType = catalogTable.getSeaTunnelRowType();
if (rowType.getFieldNames() == null || rowType.getFieldNames().length == 0
        || rowType.getFieldTypes() == null || rowType.getFieldTypes().length == 0) {
    throw new IllegalArgumentException(
        "Excel source requires a schema: define field names and types in the source config");
}

Type guard

java
static boolean hasValidSchema(SeaTunnelRowType rowType) {
    return rowType != null
        && rowType.getFieldNames() != null && rowType.getFieldNames().length > 0
        && rowType.getFieldTypes() != null && rowType.getFieldTypes().length > 0;
}

Try / catch

java
try {
    strategy.setCatalogTable(catalogTable);
} catch (FileConnectorException e) {
    if (e.getMessage().contains("Schema information is not set")) {
        LOG.error("Provide a schema for the Excel source (field names + types)", e);
    }
}

Prevention

Always declare the schema block for Excel sources — inference is not supported
When building CatalogTable programmatically, assert fieldNames.length == fieldTypes.length > 0
Resolve upstream table schema before handing the CatalogTable to the reader

When it happens

Trigger: setCatalogTable is called (by the source reader initialization or tests like testExcelRead) with a CatalogTable whose SeaTunnelRowType has null/empty field names or field types — typically a CatalogTable built without schema information.

Common situations: Programmatically building a CatalogTable/SeaTunnelRowType and forgetting to populate fields; upstream pipeline passing an unschema'd CatalogTable to the Excel source; test fixtures with empty schema arrays.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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