apache/seatunnel · error · DorisSchemaChangeException

SCHEMA_CHANGE_FAILED

SCHEMA_CHANGE_FAILED

Error message

Failed to schemaChange

What it means

Thrown by DorisSinkWriter.applySchemaChange when the SchemaChangeManager fails to apply a schema-change DDL event to the target Doris table. The writer wraps any exception from schemaChangeManager.applySchemaChange into a DorisSchemaChangeException with code SCHEMA_CHANGE_FAILED, keeping the original cause.

Source

Thrown at seatunnel-connectors-v2/connector-doris/src/main/java/org/apache/seatunnel/connectors/doris/sink/writer/DorisSinkWriter.java:232

        // In non-2PC mode each micro-batch is an independent load, so close the current load
        // first (committing the buffered rows against the still-unaltered table) before applying
        // the DDL, then reopen a fresh load so subsequent rows are loaded against the new schema.
        // Mixing schemas within a single load corrupts data (e.g. column mismatch for csv/dropped
        // columns). 2PC keeps a single transaction per checkpoint, so only name-based JSON loads
        // are allowed to cross a schema-change boundary.
        boolean flushBeforeSchemaChange = !dorisSinkConfig.getEnable2PC();
        if (flushBeforeSchemaChange) {
            flush();
        }

        this.tableSchema = tableSchemaChanger.reset(tableSchema).apply(event);
        SeaTunnelRowType seaTunnelRowType = tableSchema.toPhysicalRowDataType();
        this.serializer = createSerializer(this.dorisSinkConfig, seaTunnelRowType);

        try {
            schemaChangeManager.applySchemaChange(sinkTablePath, event);
        } catch (Exception e) {
            throw new DorisSchemaChangeException(
                    DorisConnectorErrorCode.SCHEMA_CHANGE_FAILED, "Failed to schemaChange", e);
        }

        if (flushBeforeSchemaChange) {
            startLoad(labelGenerator.generateLabel(lastCheckpointId));
        }
    }

    private void validateSchemaChangeCompatibility() {
        if (!dorisSinkConfig.getEnable2PC()) {
            return;
        }
        String format = dorisSinkConfig.getStreamLoadProps().getProperty(LoadConstants.FORMAT_KEY);
        if (!LoadConstants.JSON.equalsIgnoreCase(format)) {
            throw new DorisSchemaChangeException(
                    DorisConnectorErrorCode.SCHEMA_CHANGE_FAILED,
                    String.format(
                            "Doris schema evolution with sink.enable-2pc=true only supports "

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the wrapped cause (getCause) for the actual FE/HTTP error from Doris
2. Verify the table exists at sinkTablePath and the user has ALTER privilege
3. Reproduce the equivalent ALTER statement manually against Doris to see the rejection reason
4. Confirm the schema event is compatible (e.g. ADD COLUMN with supported types) and the database is not in a restoring/restoring-meta state
5. Ensure FE HTTP port config is correct and reachable from the job worker

Example fix

// before
schemaChangeManager.applySchemaChange(sinkTablePath, event);
// after
try {
    if (schemaChangeManager.tableExists(sinkTablePath)) {
        schemaChangeManager.applySchemaChange(sinkTablePath, event);
    }
} catch (Exception e) {
    log.warn("schema change skipped for {}: {}", sinkTablePath, e.getMessage());
}

// before submitting job
if (!dorisTableExists(sinkTablePath)) { throw new IllegalStateException("target table missing: " + sinkTablePath); }
if (!hasAlterPrivilege(user, sinkTablePath)) { throw new IllegalStateException("no ALTER privilege on " + sinkTablePath); }

try { writer.applySchemaChange(event); } catch (DorisSchemaChangeException e) { log.error("schema change failed, cause: {}", e.getCause(), e); /* decide skip vs fail */ }

When it happens

Trigger: A SchemaChangeEvent is applied via applySchemaChange (e.g. after a schema evolution event) and the Doris FE rejects the ALTER: table missing, incompatible column change, permission error, or FE/BE connectivity failure inside schemaChangeManager.applySchemaChange.

Common situations: Upstream schema changed (e.g. new column added in source DB) but Doris table disallows the corresponding ALTER; user lacks ALTER privilege; typo'd table path (sinkTablePath); Doris FE unreachable or returning HTTP errors; non-idempotent ADD COLUMN replayed after job restore.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Failed to alter table change column, SQL:
• Failed to alter table modify column, SQL:
• Failed to alter table add column, SQL:
• Failed to alter table drop column, SQL:
• SQL_OPERATION_FAILED

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