flowable/flowable-engine · error · ActivitiException

couldn't check if tables are already present using metadata:

Error message

couldn't check if tables are already present using metadata: <message>

What it means

DbSqlSession.dbSchemaCheckVersion (the schema-existence check) reads the database metadata to see whether the Flowable tables already exist. If anything goes wrong while reading metadata (e.g. tableType/catalog settings rejected, driver failures), it wraps the original message in an ActivitiException with this prefix. It signals the schema bootstrap could not even determine table presence.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java:1024

            String databaseType = dbSqlSessionFactory.getDatabaseType();

            if ("postgres".equals(databaseType)) {
                tableName = tableName.toLowerCase();
            }

            try {
                tables = databaseMetaData.getTables(catalog, schema, tableName, JDBC_METADATA_TABLE_TYPES);
                return tables.next();
            } finally {
                try {
                    tables.close();
                } catch (Exception e) {
                    LOGGER.error("Error closing meta data tables", e);
                }
            }

        } catch (Exception e) {
            throw new ActivitiException("couldn't check if tables are already present using metadata: " + e.getMessage(), e);
        }
    }

    protected String getCleanVersion(String versionString) {
        Matcher matcher = CLEAN_VERSION_REGEX.matcher(versionString);
        if (!matcher.find()) {
            throw new ActivitiException("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 ActivitiException("Illegal format for version: " + versionString, nfe);
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check the wrapped cause (`e.getMessage()` inside the message) to see why metadata access failed
2. Verify JDBC URL and credentials point to the correct database/schema
3. Confirm the JDBC driver is on the classpath and supports DatabaseMetaData.getTables
4. Test the connection with a simple metadata query outside Flowable to isolate driver vs config

Example fix

// before
String url = "jdbc:mysql://localhost/wrongdb";
// after
String url = "jdbc:mysql://localhost/flowable?useSSL=false";

try (Connection c = dataSource.getConnection()) {
  DatabaseMetaData md = c.getMetaData();
  try (ResultSet rs = md.getTables(null, null, "ACT_RU_EXECUTION", null)) {
    if (!rs.next()) throw new IllegalStateException("metadata not readable or schema empty");
  }
}

try {
  processEngine = engineCfg.buildProcessEngine();
} catch (ActivitiException e) {
  if (e.getMessage().startsWith("couldn't check if tables are already present")) {
    logger.error("Schema metadata check failed; verify JDBC URL/driver/permissions", e.getCause());
  }
  throw e;
}

When it happens

Trigger: Calling engine initialization / schema creation (e.g. databaseSchemaUpdate settings that require a schema check) when DatabaseMetaData.getTables() throws: null connection, unsupported catalog/schema parameters, or driver-level failures.

Common situations: Connecting to a database with an unsupported/misconfigured JDBC driver, wrong database name in the JDBC URL, permissions that block metadata queries, or exotic databases where tableType filtering fails.

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

• Could not set database schema on connection
• Could not retrieve database metadata:
• Could not update Flowable database schema: unknown version f
• couldn't ${operation} db schema: ${exceptionSqlStatement}
• Could not set database catalog on connection

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