flowable/flowable-engine · error · FlowableException

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

Error message

couldn't check if tables are already present using metadata: ${e.getMessage()}

What it means

AbstractSqlScriptBasedDbSchemaManager.isTablePresent inspects JDBC database metadata to detect whether Flowable tables exist. Any exception during that metadata inspection is rethrown as a FlowableException with the underlying message. The engine cannot safely determine schema state, so schema install/upgrade aborts.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/AbstractSqlScriptBasedDbSchemaManager.java:166

            if (catalog != null && catalog.length() == 0) {
                catalog = null;
            }

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

        } catch (Exception e) {
            throw new FlowableException("couldn't check if tables are already present using metadata: " + e.getMessage(), e);
        }
    }
    
    protected String prependDatabaseTablePrefix(String tableName) {
        return getDatabaseConfiguration().getDatabaseTablePrefix() + tableName;
    }
    
    public String getProperty(String propertyName) {
        return getProperty(propertyName, true);
    }

    public String getProperty(String propertyName, boolean checkPropertyTablePresent) {
        String tableName = getPropertyTable();
       
        if (checkPropertyTablePresent && !isTablePresent(tableName)) { // isTablePresent will add the prefix, so adding it later
            return null;
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Fix the underlying datasource configuration (URL, user, password) and confirm connectivity with a plain JDBC ping.
Read the chained cause exception for the real failure (SQL error, connection refused) and address it.
Verify the JDBC driver version matches the database and is on the classpath.

Example fix

// before (flowable.cfg)
<property name="jdbcUrl" value="jdbc:mysql://localhost:3306/flowable"/>
// after
<property name="jdbcUrl" value="jdbc:mysql://localhost:3306/flowable?useSSL=false"/>
<property name="jdbcUsername" value="flowable"/>
<property name="jdbcPassword" value="flowable"/>

Defensive patterns

Strategy: retry

Validate before calling

try (Connection c = dataSource.getConnection()) { DatabaseMetaData md = c.getMetaData(); md.getTables(null, null, "ACT_GE_PROPERTY", null); } // sanity check before engine startup

Try / catch

try { processEngine = engineCfg.buildProcessEngine(); } catch (FlowableException e) { log.error("schema metadata check failed: {}", e.getCause(), e.getCause()); throw e; }

Prevention

Validate datasource connectivity with a plain JDBC call before engine bootstrap
Keep the JDBC driver current and matched to the database version
Verify DB user has metadata read privileges
Inspect getCause() for the real underlying failure

When it happens

Trigger: isTablePresent running against a database whose metadata calls fail — wrong credentials, unreachable DB, driver quirks, closed connection, or restrictive permissions on DatabaseMetaData.

Common situations: First engine boot against a misconfigured datasource; databases with non-standard JDBC metadata behavior; network/firewall interruptions during startup; using an unsupported or broken JDBC driver.

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