What causes "Could not retrieve database metadata: " in flowable/flowable-engine?

Check the appended e.getMessage() (and server logs) for the root SQLException cause and fix the underlying JDBC issue first

flowable/flowable-engine · error · ActivitiException

Could not retrieve database metadata:

Error message

Could not retrieve database metadata:

What it means

Thrown by TableDataManager.getTableMetaData when a JDBC SQLException occurs while reading table metadata (column names/types) via DatabaseMetaData calls. The library wraps the underlying SQLException in an ActivitiException so callers get a uniform engine exception; the original message is appended. It indicates the schema introspection query against the database failed, not that the table is missing (a missing table returns null instead).

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/persistence/entity/TableDataManager.java:259

                        String columnName = resultSet.getMetaData().getColumnName(i + 1);
                        if ("TABLE_SCHEM".equalsIgnoreCase(columnName) || "TABLE_SCHEMA".equalsIgnoreCase(columnName)) {
                            if (!schema.equalsIgnoreCase(resultSet.getString(resultSet.getMetaData().getColumnName(i + 1)))) {
                                wrongSchema = true;
                            }
                            break;
                        }
                    }
                }

                if (!wrongSchema) {
                    String name = resultSet.getString("COLUMN_NAME").toUpperCase();
                    String type = resultSet.getString("TYPE_NAME").toUpperCase();
                    result.addColumnMetaData(name, type);
                }
            }

        } catch (SQLException e) {
            throw new ActivitiException("Could not retrieve database metadata: " + e.getMessage());
        }

        if (result.getColumnNames().isEmpty()) {
            // According to API, when a table doesn't exist, null should be returned
            result = null;
        }
        return result;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the appended e.getMessage() (and server logs) for the root SQLException cause and fix the underlying JDBC issue first
Verify the database user has permission to read metadata (e.g. INFORMATION_SCHEMA / system catalog access)
Test connectivity with the same datasource outside the engine (simple JDBC ping) to rule out network/pool problems
Confirm the JDBC driver version matches your database server version

Example fix

// before: failing on restricted metadata access
TablePage tablePage = managementService.createTablePageQuery().tableName(tableName).listPage(0, 10);
// after: guard with availability check and handle failure
if (managementService.getTableCount().containsKey(tableName.toUpperCase())) {
    try {
        TablePage tablePage = managementService.createTablePageQuery().tableName(tableName).listPage(0, 10);
    } catch (ActivitiException e) {
        LOG.warn("Table metadata unavailable: " + e.getMessage());
    }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check table existence via metadata-safe API
boolean exists = managementService.getTableCount().containsKey(tableName.toUpperCase());

Try / catch

try {
    TablePage page = managementService.createTablePageQuery().tableName(tableName).listPage(0, 10);
} catch (ActivitiException e) {
    // e.getCause()/message carries the SQLException; fall back or alert
    LOG.warn("metadata query failed: " + e.getMessage());
}

Prevention

Grant the DB user metadata/catalog read privileges
Monitor connection-pool health and keepalives
Pin a JDBC driver version compatible with your DB server
Handle a null result as 'table does not exist', not as this error

When it happens

Trigger: Calling engine APIs that introspect table metadata (e.g. TablePageQuery, schema checks, admin table listings) when the JDBC connection is broken, the user lacks metadata privileges, or the driver rejects the DatabaseMetaData/resultSet.getString("TYPE_NAME") call.

Common situations: Database user missing catalog/metadata read permissions; connection dropped by firewall or pool timeout; unsupported/buggy JDBC driver returning bad metadata; wrong database URL after a migration; database server temporarily down.

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