Why Flowable refuses to start on a mismatched database schema
FlowableWrongDbException means the engine version and the schema version recorded in the database do not match, so the engine stops during startup rather than run against tables it does not understand. Teams usually meet it right after a dependency bump, a Flowable version change in a Spring Boot or Maven build, or a redeploy that points an older database at a newer engine. Act as soon as it appears in a non-production environment, because it is a signal that the schema has not been prepared for the code that is trying to start. Do not treat it as a transient failure to retry.
The fix is a deliberate schema upgrade that you plan, run and verify, not a restart or a change to a single setting that makes the check go away. Skipping the check or forcing the engine to start against an out-of-date schema tends to surface later as failed queries, missing columns or inconsistent job data, which are harder to diagnose. The Flowable configuration docs describe how schema creation and upgrade are handled through the database settings. Confirm the exact property names, accepted values and schema table details against the documentation for the version you run, because these differ between major releases.
Before you change anything, record the engine version from your build file, the version of the database schema currently in place, and the database type and version you use. Check the supported database list and the minimum versions in the configuration docs, since an unsupported database can produce confusing startup failures of its own. The decision to make is whether the schema should be upgraded in place with the version you are moving to, or whether the deployment should roll back to the engine version that matches the database. Make that choice in a written change plan with a tested backup, not during an outage.
What triggers a version mismatch in practice
The most common trigger is a Flowable library upgrade that reaches the application before the database schema is upgraded. The engine starts, compares the version it was built with against the version recorded in the database, and refuses to run when they differ. Deployment order is the usual culprit: a container image or Spring Boot application is rolled out with a new flowable-engine dependency while the schema change is still a separate step in a runbook or an unrun script. Confirm which version table your database uses and which release recorded the last schema change before any rollout. A second trigger is a shared database. When several nodes, services or environments point at one schema, a single node running a newer engine can change the expected version for every other node, and older nodes then fail on their next start. Check every application that references the same JDBC URL and schema name, including batch jobs, test harnesses and reporting tools that happen to bootstrap an engine.
A third trigger is a schema changed outside the application. A database administrator, a migration job for another team, or a manual ALTER run during an incident can leave the schema at a version that no deployed engine expects. Ask who holds write access to the Flowable schema and whether changes are logged. The fourth trigger is rollback. When a release is reverted but the schema was already upgraded, the older code starts against a newer schema and fails the same check. Rolling back a Flowable release therefore means deciding in advance whether the schema is also restored, which is only safe if the schema change was designed to be reversed. Major releases raise the stakes. According to the Flowable 7.0.0 release notes, version 7 moved to Java 17, Spring Boot 3 and Jakarta EE, and the Flowable 8.0.0 release notes describe Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3. Those baseline changes alter the dependency set itself, so an application can fail for dependency reasons before any schema check runs. Align the Java, Spring and Jakarta versions with the target release notes before diagnosing the database.
Which schema action fits each environment
On a developer workstation, the database is usually disposable, so letting the engine create or update the schema at startup is often the fastest path. The cost of a bad schema is a database rebuild, which makes automatic changes a reasonable default for local work. The main risk is that the engine hides version drift, because the schema is rebuilt every time the application starts.
- Disposable database: Use an embedded H2 database or a throwaway container so a reset costs nothing.
- Owner: The developer who maintains the local profile owns the setting, and it stays out of shared configuration.
- Hidden drift: A schema that is rebuilt on every run never shows a mismatch, so developers do not see the errors production will see.
- DBA review: Not needed for local databases, but required before any shared development database is reused.
- Exact keys: Confirm the property names for your engine version in the configuration docs before you write them into a profile.
Check that the development profile is never copied into a shared or deployed configuration file.
Test pipelines should build a fresh schema on every run so that results are repeatable. That setup proves the new code works on a clean database, but it does not prove the engine can start against a database left by the previous release. Upgrade behavior needs its own test, and the pipeline should be set up so that a mismatch fails the build instead of being quietly fixed.
- Clean build: Create the schema in an empty database for each run, using the same engine version as the release candidate.
- Upgrade test: Start the new engine against a schema created by the last production release, and record whether startup succeeds.
- Fail on mismatch: Turn off automatic schema changes in the pipeline profile so that a version difference stops the job.
- Test data: Use masked or synthetic data. Copies of production data need security and DBA approval before they are loaded.
- Owner: The platform or QA team owns the pipeline, with the application team owning the upgrade test cases.
Confirm that your pipeline's database version matches the production engine's supported database types, as listed in the configuration docs.
In production, the schema change is a planned release event, not a side effect of startup. Automatic creation or update can run on several nodes at once and can change tables while other nodes are still using them. A controlled script, reviewed by a DBA and applied before the new engine starts, keeps the change visible, repeatable and reversible.
- Scripted change: Apply the schema scripts supplied with the release, reviewed and stored in version control, and turn off automatic schema changes at startup.
- Owner: The platform team runs the change, and the DBA signs off on the script and the rollback plan.
- Restore point: Take a backup and confirm that a restore has been tested before the change window opens.
- Rollout order: Confirm in the release notes whether old and new nodes can share one schema during a rolling update, and plan the node order around the answer.
- DBA review triggers: Require review for major version changes, large history tables, index changes and long-running locks.
Before a major upgrade, read the release notes, since changes to the Java, Spring or Jakarta baseline can require more than a schema change.
How to upgrade the schema safely
This sequence moves a Flowable schema from the version the engine expects to the version it is upgrading to, with a verified backup, a tested copy and a documented rollback point before anything changes in production. Each step leaves a check that confirms it finished before the next one begins.
Inventory engine and schema versions
Record the Flowable engine version in each application and the schema version stored in the database, including the ACT_GE_PROPERTY table entry that holds the schema version. List every environment and every node that connects to the same database, because a single node on an old engine can block a rollout. Done when you have a written table of engine version, schema version and database type for each environment and node, and the values match what the error message reports.
Back up the database before changes
Take a full, restorable backup of the Flowable database using the backup method your platform team uses for that database engine, and store it outside the database host. Confirm the backup can be restored by restoring it to a scratch instance and checking that the Flowable tables are present with row counts close to production. Done when a restore test has passed and the backup identifier is recorded in the change ticket.
Read the release notes for the target version
Read the release notes for the target Flowable version before choosing a schema path. Check for changes to the Java, Spring and Jakarta baseline, removed components and any change to the database scripts or supported database types, because these affect whether the upgrade is a schema change alone or a code migration as well. Record any items that need code or configuration changes in your application repository. Done when each item is either cleared or assigned to a named owner.
Upgrade the schema in a non-production copy
Restore the verified backup into a non-production database and run the schema upgrade against it with the same database type, version and configuration as production. Capture the upgrade output and check that the schema version reported by the engine now matches the target version. Done when the copy starts with the new engine version and no FlowableWrongDbException or schema errors appear in the startup logs.
Run engine tests against the upgraded copy
Run your process, case and decision regression tests, plus any integration tests that exercise delegates and external workers, against the upgraded copy. Include a check that the async executor picks up and completes a test job, and that a deployed definition can start an instance. Done when all tests pass and the results are saved with the schema version they ran against. A failing test is a stop point: resolve it or return to the backup before any production work.
Apply the upgrade in a maintenance window
Confirm the rollback decision point with the change owner before production changes begin: the backup from step two must be restorable, and all nodes must be stoppable together. Stop every engine node that uses the database, apply the schema upgrade with the tested script, and then deploy the matching engine version to each node. Done when the schema version in the database matches the target and every node reports the same engine version.
Verify engine start and job execution
Start the nodes one at a time and confirm each one starts without a schema error and registers with the async executor. Check that timers and async jobs run, that no new jobs appear in the deadletter table unexpectedly, and that a known test process completes end to end. Done when the engine logs show successful startup on every node, a test job completes and the monitoring you already use reports normal process activity. Record the outcome in the change ticket and keep the backup until your retention policy says otherwise.
Running mixed versions during a rolling deployment
Mixed versions are the hardest case in this topic because every node that shares one database also shares its schema. When a node on the new engine version and a node on the old one point at the same tables, either side can refuse to start, or the two can disagree about what the schema should look like. The FlowableWrongDbException you see at startup is the engine doing its job: it checks the schema version it finds against the version it was built with and stops rather than running against a schema it does not understand. Before you start a rolling deployment, confirm in the release notes for your source and target versions whether the vendor documents mixed-version operation at all. The Flowable documentation and release notes linked from this page describe upgrades in terms of a schema upgrade step, and you should not assume a staged rollout is supported unless the documentation for your exact versions says so.
The practical decision is between a short full-stop upgrade and a staged rollout. A full stop takes every node offline, applies the schema upgrade once, and starts all nodes on the new version. It is simpler to verify and to roll back as a single unit, but it means a maintenance window. A staged rollout keeps some nodes serving traffic during the change, which only makes sense when the documentation confirms the mixed state is safe for your versions. If it is not confirmed, treat the full stop as the default and ask your DeployOpen or internal engineering lead to document the reasoning. Whichever path you choose, rehearse it against a copy of production data first, since the schema step is the part that cannot be undone by restarting a node.
Locking deserves attention in any mixed-version plan. The Flowable advanced documentation describes the async executor as coordinating multiple nodes through lock owners and lock expiration times stored in the database. Expired locks are recovered and jobs are picked up by other nodes. During a mixed rollout, nodes on different versions may run timers and async jobs against the same job rows, so you should confirm how each version writes and expires those locks before allowing both to run. Watch for jobs that stay locked after a node stops, and make sure lock expiration is not so long that timers stall during the rollout. Record the lock settings and job counts before the first node changes, so you can tell a normal handover from a stuck engine.
Preventing the mismatch in CI/CD pipelines
Most FlowableWrongDbException incidents trace back to an engine JAR that moved ahead of the schema, or a schema that moved without the matching engine. The cards below are checks that catch that drift before a deployment reaches a shared environment, and they work together: pin, separate, test, version, verify and record.
Pin engine and starter versions together
Declare the Flowable engine version and every Flowable starter (process, CMMN, DMN, REST) in one place, such as a parent POM property or a version catalog, so no module can pull a different engine release. Check the resolved dependency tree in CI, not just the declared versions, because a transitive dependency can silently bring in another Flowable artifact. A single version property should be the only place a release number is changed.
Run schema upgrades as a gated job
Move schema changes out of application startup and into a separate pipeline job that runs before the application rollout starts. The job should require a manual or policy approval for production, log the schema state before and after, and stop the pipeline if it fails. This keeps a failed upgrade from leaving a half-updated database behind a running application.
Fail builds on schema disagreement
Run the build against a throwaway test database that already holds the schema from the previous release, then start the new engine against it. The build should fail if the engine reports a version that does not match the schema, which catches a bumped engine version that was never paired with an upgrade script. Use the same database type you run in production, since behavior can differ between supported databases.
Version schema scripts in source control
Keep every schema change script in the same repository and commit as the engine version it belongs to, with a clear ordering. Reviewers should see the engine bump and its schema script in one pull request. Reject any change that alters the database outside those scripts, because an untracked manual change is the most common reason two environments report different schema states.
Add a startup smoke test
After deployment, run a short test that starts the application, confirms the engine boots, deploys one sample process definition, starts an instance and completes a task. This is a stronger check than a health endpoint returning 200, because the engine may start only partially when the schema is wrong. Run it in every environment, including the one that receives the rollout first.
Record the version pairing per environment
Store the engine version, starter versions and schema level for each environment in a file or deployment record that the pipeline updates on every release. Compare this record across development, test and production before promotion. A mismatch between environments is visible at a glance, which shortens investigation when a rollback or a delayed environment causes errors.
Which dependencies must move together
This table compares the baseline changes in Flowable 7.0.0 and 8.0.0 that affect which engine, framework and library versions must line up. Read each row as a dependency that has to match the engine version in your build, and use the last column to list what your team must confirm before changing the engine version.
| Dependency | Flowable 7.0.0 change | Flowable 8.0.0 change | What to confirm in your build |
|---|---|---|---|
| Java version | Moved to Java 17 | No change listed in the release notes | Confirm the JDK your build and runtime images use is 17 or later |
| Spring Boot version | Moved to Spring Boot 3 | Requires Spring Boot 4, with no backward compatibility for Spring Boot 3 | Confirm the Spring Boot parent and starter versions in every module |
| Spring Framework version | Follows Spring Boot 3 | Upgraded to Spring Framework 7 | Confirm transitive Spring jars resolve to one version across modules |
| Jakarta EE usage | Moved to Jakarta EE namespaces | Follows the Spring Boot 4 baseline | Confirm no javax imports remain in delegates, listeners or custom code |
| JSON library | Not listed as a default change in the release notes | Jackson 3 is the default, with a Jackson 2 compatibility layer | Confirm which Jackson artifacts your custom serializers and REST clients import |
| Test framework | Not listed in the release notes | JUnit 3 and 4 support removed | Confirm test classes run on JUnit 5 and no JUnit 4 runners remain |
| Removed components | UI applications, form and content engines, Mule integration and async history removed | Not listed in the release notes | Confirm your deployment does not depend on any removed component |
Security and operational considerations during schema changes
A schema change touches the most sensitive state the engine holds: process instances, tasks, jobs and history. The cards below cover the access, recovery, approval, separation and monitoring controls that should surround any version upgrade, so that a failed boot is contained and traceable.
Scope database privileges for schema changes
The account that runs the engine's schema upgrade needs DDL rights on the Flowable tables, which is far more than the runtime account should hold. Before the change, confirm with your DBA which privileges the upgrade needs on the target database, such as ALTER and CREATE on the Flowable schema, and grant them only for the upgrade window. Check that no broader rights, such as schema owner on other applications, are included by accident. Supported database types are listed in the Flowable configuration docs, and privilege syntax differs between them.
Back up and test restore before upgrading
A backup taken minutes before the change is the only safe rollback once a schema upgrade has altered tables and data. Capture a full database backup and confirm it restores into a separate environment before the production window opens. Record the restore time and the exact Flowable engine version that the backup matches, so you know which binaries can run against it. Ask your team to confirm whether the backup includes the async job and lock tables, since in-flight work depends on them.
Put schema changes under change control
Treat each engine version change as a change record with a named owner, a reviewer, a rollback plan and a go or no-go decision. Attach the release notes for the target version to the record, so reviewers can check for removed components and dependency baseline changes. Confirm whether your change board classifies a schema upgrade as standard or normal, because that decides who must approve it. Keep the record linked to the pipeline run that applied the change.
Separate database and application accounts
The runtime application should connect with an account that can read and write engine data but cannot alter the schema. A separate migration account, held in a secrets manager and used only by the deployment job, limits what a compromised application can do to the database. Check that the runtime account cannot drop or truncate Flowable tables, and that the migration credential is not stored in application configuration files. Rotate both credentials on the schedule your security policy sets.
Audit who ran schema changes
Record the identity, time, host, engine version and script run for every schema change, and keep those records outside the database being changed. Database audit logging, if your platform offers it, should capture DDL statements against Flowable tables. Pipeline logs should retain the job that ran the change and the approval it referenced. Confirm with your auditors how long these records must be kept and who can read them.
Monitor for failed boots after deployment
A version mismatch usually shows up as an engine that refuses to start, so alert on repeated startup failures and failing health checks in the minutes after each deployment. Watch for the FlowableWrongDbException message in startup logs and for pods or services that restart in a loop. Pair these alerts with a check that the engine's job executor is running once the service is healthy. Confirm that your alerting routes these failures to the team that owns the deployment, not only to a general queue.
Limits to confirm before you upgrade
Which databases does Flowable support for the engine schema?
The Flowable configuration docs list H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server as supported database types. Confirm the exact database version you run against the configuration documentation and the release notes for the Flowable version you plan to move to, because support can differ by engine version. For MySQL, the docs note that versions below 5.6.4 lack millisecond precision, which affects timestamps the engine stores for jobs and history. If you run an older MySQL release, check that point before you change anything else, since a timestamp issue can look like a schema problem.
Does Flowable support rolling upgrades between two versions?
Do not assume it does. Confirm with Flowable whether the version pair you plan to run supports nodes on different engine versions sharing one database, and read the release notes for the target version before you schedule a rollout. The mismatch error exists because the engine refuses to start against a schema it does not expect, so a mixed-version cluster is only safe if the vendor documents that the two versions can share the schema during the transition. If the answer is no or unclear, plan a maintenance window in which all nodes stop, the schema is upgraded and all nodes start on the new version.
How does the schema change between Flowable versions?
Ask Flowable which schema scripts ship with the target version, which tables or columns it adds, changes or drops, and whether the upgrade runs automatically at startup or needs a manual script. The answer determines whether you can take a database backup and roll back, and how long the migration takes on your data volume. Test the upgrade against a copy of production data with the same database engine and version, and record the schema version before and after. Do not rely on a development database with a few process instances to predict production behavior.
Does a custom identity service affect a Flowable upgrade?
It can. The Flowable docs allow identity management to be replaced by overriding IdmIdentityServiceImpl or by implementing the IdmIdentityService interface, and an LDAP implementation is provided as a reference. Any custom class that extends or replaces an engine class depends on the internal API of that version, so a change to the interface or base class can break compilation or behavior after an upgrade. Inventory every override, extension, custom delegate and listener, check each one against the target version's release notes, and run your integration tests against the new engine before cutover.
Which framework and Java baseline changes come with the target version?
Read the release notes for every major version between your current release and the target. The Flowable 7.0.0 release notes say version 7 moved to Java 17, Spring Boot 3 and Jakarta EE, and removed the UI applications, the form and content engines, Mule integration and async history. The Flowable 8.0.0 release notes describe the move to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3, Jackson 3 as the default JSON library, and removal of JUnit 3 and 4 support. Confirm which of these affect your application, your build and your runtime image before you plan the schema step.
Can we run the schema upgrade and the application upgrade separately?
Ask Flowable whether the engine version you choose can run against the previous schema for a transition period, and whether the schema upgrade can be applied before the application is redeployed. If the answer is no, the schema change and the application change must happen together, which raises the risk of the window. If the answer is yes, document the order, the rollback path and the point after which rollback is no longer possible. Your own change process will decide how long each step can stay open.
What should we confirm about the Flowable async executor during an upgrade?
Confirm how the async executor behaves when nodes on different versions share a database. The Flowable advanced documentation describes lock owners and lock expiration times stored in the database, which let other nodes pick up jobs after a lock expires. Ask whether lock and job tables change between versions, whether jobs locked by an old node are recovered correctly by a new one, and whether you should drain or stop the executor before the upgrade. Check job state before and after the change so you can tell an upgrade problem from a job that was already stuck.
Who should confirm these limits before we commit to an upgrade plan?
Your platform team owns the database, the deployment pipeline and the rollback plan. Your application team owns custom delegates, identity services, extensions and tests. Flowable can confirm supported databases, version compatibility and schema behavior for the versions you name. If you want an implementation partner to do the inventory, the test upgrade and the cutover plan, the scope is agreed in writing before work starts and the quote follows from that scope. Ask for the written list of confirmed limits as a deliverable so the decision rests on documented answers.
Where to confirm version details
Before you change any version pin or run a schema upgrade, confirm the exact engine and database versions you are moving between. The Flowable 8.0.0 release notes are the first place to check if your target is the 8.x line, because they describe the move to Spring Framework 7 and Spring Boot 4, the lack of backward compatibility with Spring Boot 3, and the change of the default JSON library to Jackson 3. The Flowable 7.0.0 release notes answer the same questions for teams still on the 6.x line, including the move to Java 17, Spring Boot 3 and Jakarta EE. Read both in order if you are skipping a major version, since a dependency change in one release can make the schema step in the next one fail for reasons unrelated to the database.
Use the Flowable configuration docs to confirm which database types and minimum database versions your target engine supports, and how the schema is created or updated at startup. The Spring Boot docs answer which starter and Spring Boot version pairs with your engine, and which properties control schema handling in a Spring application. Record the engine version, the database driver version and the schema version in your change ticket, then compare them against what the documentation states for the target release. If any of these values are missing from the docs for your exact release, confirm them with Flowable or in a test environment before the production window.
How DeployOpen scopes and delivers Flowable upgrade work
DeployOpen approaches schema version mismatch work as a bounded engagement: we confirm which engine and database versions are running, agree the target state in writing, and plan the schema change before anything touches production. The work runs inside your infrastructure, with testing, documentation and handover covered in the written scope.
How we scope
- Inventory engine, starter and database versions across every node, environment and pipeline that starts Flowable.
- Record which Flowable schema version each database holds and where the mismatch was introduced.
- Agree in writing the target versions, rollout order, rollback position and any mixed-version window to be tolerated.
How we build
- Prepare dependency changes for the target release, including any Spring or Java baseline the chosen version requires.
- Rehearse the schema upgrade on a restored copy of production data before any change in a live environment.
- Add a pipeline check that fails the build when the engine version and database schema version disagree.
How we hand over
- Deliver a runbook covering the upgrade order, verification queries, and the steps to stop a rollout that stalls.
- Document the pipeline gate, its failure messages, and who owns it after handover.
- Walk your platform and engineering teams through the procedure and the evidence produced during rehearsal.
How we support
- Engagements are fixed-scope, so scope, deliverables and timelines are agreed before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately.
- Confirm with us, before signing, which post-handover support terms apply to your environment.
