flowable/flowable-engine · error · FlowableException

Illegal format for version: ${versionString}

Error message

Illegal format for version: ${versionString}

What it means

Flowable throws this when upgrading a process-engine schema: the version string found in the database metadata does not match the expected format (e.g. '6.7.2'). getCleanVersion uses CLEAN_VERSION_REGEX to extract a numeric version prefix; if the regex does not match, the string is not a recognizable version and schema upgrade logic aborts.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java:252

            if (lockManager != null) {
                lockManager.releaseLock();
            }
        }

    }

    public boolean isEngineTablePresent() {
        return isTablePresent("ACT_RU_EXECUTION");
    }

    public boolean isHistoryTablePresent() {
        return isTablePresent("ACT_HI_PROCINST");
    }

    protected String getCleanVersion(String versionString) {
        Matcher matcher = CLEAN_VERSION_REGEX.matcher(versionString);
        if (!matcher.find()) {
            throw new FlowableException("Illegal format for version: " + versionString);
        }

        String cleanString = matcher.group();
        try {
            Double.parseDouble(cleanString); // try to parse it, to see if it is
                                             // really a number
            return cleanString;
        } catch (NumberFormatException nfe) {
            throw new FlowableException("Illegal format for version: " + versionString, nfe);
        }
    }

    protected ProcessEngineConfigurationImpl getProcessEngineConfiguration() {
        return CommandContextUtil.getProcessEngineConfiguration();
    }

    @Override
    protected String getResourcesRootDirectory() {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Inspect the schema version property (ACT_GE_PROPERTY row schema.version / schema.history) and correct it to a valid Flowable version string such as '6.7.2'
2. If the DB is from an unsupported lineage, use the official upgrade scripts instead of auto-upgrade
3. Set databaseSchemaUpdate to 'false' and manage schema versions manually with the provided SQL scripts
4. Restore the version metadata from a backup of a healthy environment

Example fix

// before (corrupted schema property)
schema.version = 'unknown'
// after
UPDATE ACT_GE_PROPERTY SET VALUE_ = '6.7.2' WHERE NAME_ = 'schema.version';

String v = managementService.getProperties().get("schema.version");
if (v == null || !v.matches("\\d+(\.\d+)*")) {
    throw new IllegalStateException("Corrupted schema.version property: " + v);
}

When it happens

Trigger: Running Flowable with schema-upgrade enabled against a database whose Flowable version marker (e.g. in ACT_GE_PROPERTY / schema version property) is missing, empty, corrupted, or a non-numeric/custom string that CLEAN_VERSION_REGEX cannot match.

Common situations: Database was created by a different tool or hand-edited; version property row was truncated; migrating between major Flowable/Acitiviti lineages where version strings differ; copying schema metadata between environments.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• resource '${resourceName}' is not available
• error while executing database update java class '${upgrades
• version mismatch: library version is '${currentVersion}', db
• There are app definitions with key = '' and version = ''
• no case definition deployed with key = '<caseDefinitionKey>'

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