What causes "couldn't get db schema version" in flowable/flowable-engine?

Inspect the cause (getCause()) for the real exception — the message itself is generic.

flowable/flowable-engine · error · FlowableException

couldn't get db schema version

Error message

couldn't get db schema version

What it means

Generic wrapper thrown when schemaCheckVersion fails with a checked (non-Runtime) exception that is not a missing-tables error. Flowable rethrows RuntimeExceptions as-is but wraps checked exceptions in a FlowableException with this fixed message, preserving the cause.

Source

Thrown at modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/db/IdmDbSchemaManager.java:96

           String errorMessage = null;
           if (!isTablePresent(IDM_PROPERTY_TABLE)) {
               errorMessage = addMissingComponent(errorMessage, "engine");
           }

           if (errorMessage != null) {
               throw new FlowableException("Flowable IDM database problem: " + errorMessage);
           }

       } catch (Exception e) {
           if (isMissingTablesException(e)) {
               throw new FlowableException(
                       "no flowable tables in db. set <property name=\"databaseSchemaUpdate\" to value=\"true\" or value=\"create-drop\" (use create-drop for testing only!) in bean processEngineConfiguration in flowable.cfg.xml for automatic schema creation",
                       e);
           } else {
               if (e instanceof RuntimeException) {
                   throw (RuntimeException) e;
               } else {
                   throw new FlowableException("couldn't get db schema version", e);
               }
           }
       }

       logger.debug("flowable idm db schema check successful");
   }
   
   protected String addMissingComponent(String missingComponents, String component) {
       if (missingComponents == null) {
           return "Tables missing for component(s) " + component;
       }
       return missingComponents + ", " + component;
   }

   @Override
   public String getContext() {
       return SCHEMA_COMPONENT;
   }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the cause (getCause()) for the real exception — the message itself is generic.
Verify DB connectivity: URL, credentials, and that the database is reachable from the app.
Ensure the JDBC driver matches your database vendor and version.
Grant the DB user rights to read the Flowable schema tables, then restart.

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check connectivity before engine bootstrap
try (Connection c = dataSource.getConnection()) { /* db reachable */ }

Try / catch

try {
  idmEngine = config.buildEngine();
} catch (FlowableException e) {
  if ("couldn't get db schema version".equals(e.getMessage())) {
    log.error("Schema check failed", e.getCause()); // real root cause is in getCause()
  }
  throw e;
}

Prevention

Always inspect getCause() — this message hides the real exception.
Use a driver version certified for your database.
Test DB connectivity and credentials before engine startup.
Grant the app DB user read access to the Flowable schema.

When it happens

Trigger: Any checked exception during the IDM schema version check that is not classified as a missing-tables exception — e.g. SQL syntax errors, driver-level SQLExceptions, connection failures surfaced as checked exceptions.

Common situations: Unsupported JDBC driver; database connectivity problems (wrong host/port, TLS issues); database user lacking privileges to query ACT_ID_PROPERTY.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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