pinpoint-apm/pinpoint · error · IllegalArgumentException

Unexpected schema change log execution order for

Error message

Unexpected schema change log execution order for 

What it means

ChangeSetManager.verifyChangeLog compares the change log's recorded execution order with the expected order of the ChangeSet in the current list. A mismatch throws IllegalArgumentException, meaning the ordering of change sets in code no longer matches the order in which they were applied to HBase.

Source

Thrown at hbase/hbase-schema/src/main/java/com/navercorp/pinpoint/hbase/schema/core/ChangeSetManager.java:111

        sortedSchemaChangeLogs.sort(Comparator.comparingInt(SchemaChangeLog::getExecOrder));
        return sortedSchemaChangeLogs;
    }

    private void verifyChangeLog(SchemaChangeLog schemaChangeLog, ChangeSet changeSet, int expectedOrder) {
        String changeSetId = changeSet.getId();
        String schemaChangeLogId = schemaChangeLog.getId();
        if (!changeSetId.equals(schemaChangeLogId)) {
            throw new IllegalArgumentException("Unexpected schema change log id, expected : " + changeSetId + " , was : " + schemaChangeLogId);
        }

        CheckSum actualCheckSum = schemaChangeLog.getCheckSum();
        CheckSum expectedCheckSum = CheckSum.compute(actualCheckSum.getVersion(), changeSet.getValue());
        if (!expectedCheckSum.equals(actualCheckSum)) {
            throw new IllegalArgumentException("Unexpected schema change log check sum for : " + schemaChangeLogId);
        }
        int actualOrder = schemaChangeLog.getExecOrder();
        if (expectedOrder != actualOrder) {
            throw new IllegalArgumentException("Unexpected schema change log execution order for " + schemaChangeLogId + ", expected : " + expectedOrder + ", was : " + actualOrder);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Reorder the change set list so each ChangeSet keeps the execOrder recorded in the change log table.
2. Append new change sets at the end of the list; never insert or remove earlier ones.
3. If removal is required, update the stored change log execution orders to match the new sequence.

Example fix

// before
changeSets.add(0, newChangeSet); // inserted in the middle
// after
changeSets.add(newChangeSet); // appended after existing change sets

// Assert list order matches stored exec orders before applying
for (int i = 0; i < changeSets.size(); i++) {
    SchemaChangeLog log = logsById.get(changeSets.get(i).getId());
    if (log != null && log.getExecOrder() != i) {
        throw new IllegalStateException(changeSets.get(i).getId() + " order drifted: expected " + i + " was " + log.getExecOrder());
    }
}

try {
    manager.getExecutedChangeSets(changeSets);
} catch (IllegalArgumentException e) {
    logger.error("Execution order verification failed: {}", e.getMessage());
}

When it happens

Trigger: Calling getExecutedChangeSets or filterExecutedChangeSets when the position of a ChangeSet in the change set list changed (inserted, removed, reordered) relative to the execOrder stored in the change log table.

Common situations: Inserting a new change set in the middle of the list instead of appending at the end; deleting an old change set class so subsequent change sets shift position.

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

• Unexpected schema change log id, expected :
• Unexpected schema change log check sum for :
• Error applying changeSet :
• Cannot create an existing table :
• Cannot modify a non-existent table :

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/701135003e52b382. Report an issue: GitHub.