{"record":{"id":"6584f1c3825a6616","repo":"flowable/flowable-engine","slug":"couldn-t-check-if-tables-are-already-present-using-6584f1","errorCode":null,"errorMessage":"couldn't check if tables are already present using metadata: <message>","messagePattern":"couldn't check if tables are already present using metadata: <message>","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java","lineNumber":1024,"sourceCode":"            String databaseType = dbSqlSessionFactory.getDatabaseType();\n\n            if (\"postgres\".equals(databaseType)) {\n                tableName = tableName.toLowerCase();\n            }\n\n            try {\n                tables = databaseMetaData.getTables(catalog, schema, tableName, JDBC_METADATA_TABLE_TYPES);\n                return tables.next();\n            } finally {\n                try {\n                    tables.close();\n                } catch (Exception e) {\n                    LOGGER.error(\"Error closing meta data tables\", e);\n                }\n            }\n\n        } catch (Exception e) {\n            throw new ActivitiException(\"couldn't check if tables are already present using metadata: \" + e.getMessage(), e);\n        }\n    }\n\n    protected String getCleanVersion(String versionString) {\n        Matcher matcher = CLEAN_VERSION_REGEX.matcher(versionString);\n        if (!matcher.find()) {\n            throw new ActivitiException(\"Illegal format for version: \" + versionString);\n        }\n\n        String cleanString = matcher.group();\n        try {\n            Double.parseDouble(cleanString); // try to parse it, to see if it is really a number\n            return cleanString;\n        } catch (NumberFormatException nfe) {\n            throw new ActivitiException(\"Illegal format for version: \" + versionString, nfe);\n        }\n    }\n","sourceCodeStart":1006,"sourceCodeEnd":1042,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java#L1006-L1042","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped cause (`e.getMessage()` inside the message) to see why metadata access failed","Verify JDBC URL and credentials point to the correct database/schema","Confirm the JDBC driver is on the classpath and supports DatabaseMetaData.getTables","Test the connection with a simple metadata query outside Flowable to isolate driver vs config"],"exampleFix":"// before\nString url = \"jdbc:mysql://localhost/wrongdb\";\n// after\nString url = \"jdbc:mysql://localhost/flowable?useSSL=false\";","handlingStrategy":"try-catch","validationCode":"try (Connection c = dataSource.getConnection()) {\n  DatabaseMetaData md = c.getMetaData();\n  try (ResultSet rs = md.getTables(null, null, \"ACT_RU_EXECUTION\", null)) {\n    if (!rs.next()) throw new IllegalStateException(\"metadata not readable or schema empty\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  processEngine = engineCfg.buildProcessEngine();\n} catch (ActivitiException e) {\n  if (e.getMessage().startsWith(\"couldn't check if tables are already present\")) {\n    logger.error(\"Schema metadata check failed; verify JDBC URL/driver/permissions\", e.getCause());\n  }\n  throw e;\n}","preventionTips":["Validate the JDBC connection and DatabaseMetaData access before engine startup","Keep the JDBC driver on the classpath and version-matched to the database","Grant the DB user permission to query system metadata tables"],"tags":["database","schema","metadata","jdbc"],"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"}