flowable/flowable-engine · error · RuntimeException

Failed to get change log version from ${changeLogTableName}

Error message

Failed to get change log version from ${changeLogTableName}

What it means

Raised inside getChangeLogVersion when a SQLException occurs while reading the Flowable change-log table (e.g. FLW_EV_DATABASECHANGELOG / Liquibase-style changelog) during schema update. It signals the change-log table exists but its version could not be read; wrapped RuntimeException keeps the SQLException as cause.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/EngineSqlScriptBasedDbSchemaManager.java:217

                String changeLogVersion = null;
                try (ResultSet resultSet = statement.executeQuery()) {
                    while (resultSet.next()) {
                        String changeLogVersionId = resultSet.getString(1);
                        int changeLogVersionOrder = getChangeLogVersionOrder(changeLogVersionId);
                        if (changeLogVersionOrder > latestChangeLogVersionOrder) {
                            // Even though we are ordering by DATEEXECUTED, and the last ID should be the last executed one.
                            // It is still possible that there are multiple entries with the same DATEEXECUTED value and the order might not be correct.
                            // e.g. MySQL 8.0 sometimes does not return the correct order.
                            changeLogVersion = changeLogVersionId;
                            latestChangeLogVersionOrder = changeLogVersionOrder;
                        }
                    }
                }
                if (changeLogVersion != null) {
                    return new ChangeLogVersion(changeLogVersion, getDbVersionForChangelogVersion(changeLogVersion));
                }
            } catch (SQLException e) {
                throw new RuntimeException("Failed to get change log version from " + changeLogTableName, e);
            }
        }

        return new ChangeLogVersion(null, getDbVersionForChangelogVersion(null));
    }

    public record ChangeLogVersion(String version, String dbVersion) {
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Read the cause SQLException for the exact SQL error (lock, privilege, missing column).
2. Repair or recreate the change-log table from a clean state (backup, drop, let Flowable rebuild and re-run updates).
3. Ensure no other engine instance holds a lock on the changelog during startup.
4. Grant the DB user SELECT/UPDATE rights on the Flowable change-log tables.

Example fix

// before: guessing at cause
catch (FlowableException e) { log.error(e.getMessage()); }
// after
catch (FlowableException e) { log.error("changelog read failed", e.getCause()); /* then repair FLW change-log table */ }

try (ResultSet rs = c.getMetaData().getColumns(null, null, "FLW_EV_DATABASECHANGELOG", null)) { if (!rs.next()) throw new IllegalStateException("change-log table missing/corrupt"); }

catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to get change log version")) { repairOrRecreateChangelog(); } else { throw e; } }

When it happens

Trigger: schemaUpdateInLock -> getChangeLogVersion executes SQL against changeLogTableName and the JDBC call throws: table locked, column missing, corrupted changelog, insufficient SELECT privilege, or connection failure mid-read.

Common situations: Interrupted previous schema update left the changelog in a bad state; DBA altered/renamed the change-log table; concurrent engine boots contending on the changelog; user lacks privileges on FLW_* change-log tables.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• couldn't get ${context} db schema version
• couldn't ${operation} db schema: ${exceptionSqlStatement}
• No flowable tables in DB. Set property "databaseSchemaUpdate
• version mismatch: library version is '${engineVersion}', db
• version mismatch: library version is '${FlowableVersions.CUR

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/85d0daa668208813. Report an issue: GitHub.