{"record":{"id":"8d82e4a8d7837bba","repo":"flowable/flowable-engine","slug":"could-not-retrieve-database-metadata","errorCode":null,"errorMessage":"Could not retrieve database metadata: ","messagePattern":"Could not retrieve database metadata: ","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/persistence/entity/TableDataManager.java","lineNumber":259,"sourceCode":"                        String columnName = resultSet.getMetaData().getColumnName(i + 1);\n                        if (\"TABLE_SCHEM\".equalsIgnoreCase(columnName) || \"TABLE_SCHEMA\".equalsIgnoreCase(columnName)) {\n                            if (!schema.equalsIgnoreCase(resultSet.getString(resultSet.getMetaData().getColumnName(i + 1)))) {\n                                wrongSchema = true;\n                            }\n                            break;\n                        }\n                    }\n                }\n\n                if (!wrongSchema) {\n                    String name = resultSet.getString(\"COLUMN_NAME\").toUpperCase();\n                    String type = resultSet.getString(\"TYPE_NAME\").toUpperCase();\n                    result.addColumnMetaData(name, type);\n                }\n            }\n\n        } catch (SQLException e) {\n            throw new ActivitiException(\"Could not retrieve database metadata: \" + e.getMessage());\n        }\n\n        if (result.getColumnNames().isEmpty()) {\n            // According to API, when a table doesn't exist, null should be returned\n            result = null;\n        }\n        return result;\n    }\n\n}\n","sourceCodeStart":241,"sourceCodeEnd":270,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/persistence/entity/TableDataManager.java#L241-L270","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: failing on restricted metadata access\nTablePage tablePage = managementService.createTablePageQuery().tableName(tableName).listPage(0, 10);\n// after: guard with availability check and handle failure\nif (managementService.getTableCount().containsKey(tableName.toUpperCase())) {\n    try {\n        TablePage tablePage = managementService.createTablePageQuery().tableName(tableName).listPage(0, 10);\n    } catch (ActivitiException e) {\n        LOG.warn(\"Table metadata unavailable: \" + e.getMessage());\n    }\n}","handlingStrategy":"try-catch","validationCode":"// pre-check table existence via metadata-safe API\nboolean exists = managementService.getTableCount().containsKey(tableName.toUpperCase());","typeGuard":null,"tryCatchPattern":"try {\n    TablePage page = managementService.createTablePageQuery().tableName(tableName).listPage(0, 10);\n} catch (ActivitiException e) {\n    // e.getCause()/message carries the SQLException; fall back or alert\n    LOG.warn(\"metadata query failed: \" + e.getMessage());\n}","preventionTips":["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"],"tags":["database","jdbc","metadata","sql"],"backgroundTag":"database-query-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}