flowable/flowable-engine · error · FlowableException

Could not retrieve database metadata: " + e.getMessage()

Error message

Could not retrieve database metadata: " + e.getMessage()

What it means

Wrapper thrown by TableDataManagerImpl.getTableMetaData: reading DatabaseMetaData while enumerating tables (catalog/schema listing) failed with a SQLException; database connectivity or metadata permissions are broken.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/persistence/entity/TableDataManagerImpl.java:199

                        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(Locale.ROOT);
                    String type = resultSet.getString("TYPE_NAME").toUpperCase(Locale.ROOT);
                    result.addColumnMetaData(name, type);
                }
            }

        } catch (SQLException e) {
            throw new FlowableException("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;
    }
    
    protected DbSqlSession getDbSqlSession() {
        return Context.getCommandContext().getSession(DbSqlSession.class);
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify database connectivity and metadata privileges of the datasource user
2. Check the cause SQLException for the driver-level failure reason

try {
    TableMetaData meta = tableDataManager.getTableMetaData(tableName);
} catch (FlowableException e) {
    LOGGER.error("Column metadata failed for {}: {}", tableName, e.getMessage(), e);
}

When it happens

Trigger: Querying a table's metadata via TableDataManager (e.g. from schema checks or table info queries) when getColumns() fails, or when the queried table name is invalid for the driver.

Common situations: Driver rejects case-sensitive or schema-qualified table names; metadata access denied; transient connection failure; table name uses reserved characters not escaped by the filter.

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

• couldn't check if tables are already present using metadata:
• SQL Exception when getting value. Message: ${e.getMessage()}
• couldn't ${operation} db schema: ${exceptionSqlStatement}
• couldn't get ${context} db schema version
• Failed to get change log version from ${changeLogTableName}

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