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

Inspect the cause chain of the thrown FlowableException for the root SQLException and fix that underlying problem.

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 catches a non-missing-tables, non-RuntimeException (checked) exception while checking or reading the DB schema version. The original exception is attached as the cause; the message only indicates the version check could not complete.

Source

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

            }
            if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed() && !isHistoryTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, "history");
            }

            if (errorMessage != null) {
                throw new FlowableException("Flowable 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 db schema check successful");
    }

    protected String addMissingComponent(String missingComponents, String component) {
        if (missingComponents == null) {
            return "Tables missing for component(s) " + component;
        }
        return missingComponents + ", " + component;
    }

    protected String getDbVersion() {
        DbSqlSession dbSqlSession = CommandContextUtil.getDbSqlSession();
        String selectSchemaVersionStatement = dbSqlSession.getDbSqlSessionFactory().mapStatement("org.flowable.common.engine.impl.persistence.entity.PropertyEntityImpl.selectPropertyValue");
        return dbSqlSession.getSqlSession().selectOne(selectSchemaVersionStatement, "schema.version");

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the cause chain of the thrown FlowableException for the root SQLException and fix that underlying problem.
Verify JDBC connectivity, driver version, and that the DB user can read ACT_GE_PROPERTY and database metadata.
Check Flowable's databaseType detection / supported database list; set databaseType explicitly if auto-detection fails on an unsupported DB.

Example fix

// before
// cause hidden: FlowableException("couldn't get db schema version", e)
// after: log the cause to find root issue
try { processEngine = cfg.buildProcessEngine(); }
catch (FlowableException e) { LOG.error("schema check failed", e.getCause()); throw e; }

Defensive patterns

Strategy: try-catch

Validate before calling

try { managementService.getProperties(); } catch (Exception e) { LOG.error("DB schema check will fail", e); }

Try / catch

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { Throwable root = e; while (root.getCause() != null) root = root.getCause(); LOG.error("root schema-check failure", root); }

Prevention

Always inspect the cause chain when this generic message appears
Verify JDBC driver version matches the database before engine startup
Confirm DB user read access to ACT_GE_PROPERTY and metadata tables

When it happens

Trigger: getDbVersion() or table-presence checks throw a checked/wrapped exception — e.g. SQL errors surfaced as non-runtime exceptions, driver/classloader issues, or any unexpected Exception during the schema check.

Common situations: Broken/mismatched JDBC driver causing SQLExceptions wrapped oddly; network interruptions mid-check; permissions problems on the metadata queries; custom DbSqlSessionFactory misconfiguration.

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/e41ebc96e9ef2453. Report an issue: GitHub.