apache/seatunnel · error · CatalogException

Type mismatch for column

Error message

Type mismatch for column '%s' inside target BigQuery table '%s'. Source type: '%s', target type: '%s'

What it means

This CatalogException is thrown by BigQuerySaveModeHandler.validateSchemaCoherence when isTypeCompatible determines that the SeaTunnel SqlType of a source column cannot be written into the corresponding BigQuery column's SqlType in save-mode ERROR. Both the source and target types are reported in the message. It prevents silent data corruption from incompatible type coercions.

Solutions

1. Cast the conflicting column in the SeaTunnel config (e.g. via a transform or source read options) to match the BigQuery type, or ALTER the BigQuery column type if safely castable
2. Set schema_save_mode=EVOLVE_SCHEMA / allow type evolution so the handler reconciles types
3. Recreate the target table with types matching the source schema
4. Check isTypeCompatible rules to pick a supported type pair

Example fix

// before
schema_save_mode = ERROR   // source INT64 vs target STRING -> mismatch
// after
schema_save_mode = EVOLVE_SCHEMA
// or transform source: CAST(id AS STRING)

for (Column c : sourceSchema.getColumns()) {
    Column rc = remoteSchema.getColumn(c.getName());
    if (rc != null && !compatible(c.getDataType().getSqlType(), rc.getDataType().getSqlType())) {
        LOG.error("Type mismatch on column " + c.getName() + ": "
            + c.getDataType().getSqlType() + " vs " + rc.getDataType().getSqlType());
    }
}

try {
    handler.handleSchemaSaveMode();
} catch (CatalogException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Type mismatch for column")) {
        LOG.error("Align column types (cast in source/transform) or enable EVOLVE_SCHEMA");
    }
    throw e;
}

When it happens

Trigger: Running a sink with schema_save_mode=ERROR against an existing BigQuery table whose column type is incompatible with the source — e.g. source STRING vs target INT64, source DECIMAL vs target STRING, source TIMESTAMP vs target DATE, or source array/struct types that the compatibility map disallows.

Common situations: Table created earlier with different types; upstream connector schema changed (e.g. int -> string); BigQuery maps a column to a narrower type; user expects implicit casts that the strict compatibility check rejects.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Failed to validate BigQuery schema coherence
• Target BigQuery table
• Vitess CDC requires explicit schema metadata through either…
• ADD_BATCH_DATA_FAILED
• All candidate sink tables were skipped in Spark starter.

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-bigquery/src/main/java/org/apache/seatunnel/connectors/bigquery/sink/BigQuerySaveModeHandler.java:115

            for (Column sourceColumn : catalogTable.getTableSchema().getColumns()) {
                Optional<Column> remoteColOpt =
                        remoteTable.getTableSchema().getColumns().stream()
                                .filter(c -> c.getName().equalsIgnoreCase(sourceColumn.getName()))
                                .findFirst();

                if (!remoteColOpt.isPresent()) {
                    throw new CatalogException(
                            String.format(
                                    "Target BigQuery table '%s' is missing source column: '%s'",
                                    tablePath.getFullName(), sourceColumn.getName()));
                }

                Column remoteColumn = remoteColOpt.get();
                if (!isTypeCompatible(
                        sourceColumn.getDataType().getSqlType(),
                        remoteColumn.getDataType().getSqlType())) {
                    throw new CatalogException(
                            String.format(
                                    "Type mismatch for column '%s' inside target BigQuery table '%s'. Source type: '%s', target type: '%s'",
                                    sourceColumn.getName(),
                                    tablePath.getFullName(),
                                    sourceColumn.getDataType().getSqlType(),
                                    remoteColumn.getDataType().getSqlType()));
                }
            }
            log.info(
                    "BigQuery schema coherence check passed successfully for table: {}",
                    tablePath.getFullName());
        } catch (TableNotExistException e) {
            log.info(
                    "Target BigQuery table '{}' does not exist yet. Skipping schema coherence check.",
                    tablePath.getFullName());
            return;
        } catch (Exception e) {
            if (e instanceof CatalogException) {

View on GitHub (pinned to cf67b549a7)