{"record":{"id":"ed848cb1a83d42e7","repo":"flowable/flowable-engine","slug":"exception-while-initializing-database-connection","errorCode":null,"errorMessage":"Exception while initializing Database connection","messagePattern":"Exception while initializing Database connection","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/util/DbUtil.java","lineNumber":116,"sourceCode":"                    if (resultSet.next()) {\n                        version = resultSet.getString(\"version\");\n                    }\n\n                    if (StringUtils.isNotEmpty(version) && version.toLowerCase().startsWith(PRODUCT_NAME_CRDB.toLowerCase())) {\n                        databaseProductName = PRODUCT_NAME_CRDB;\n                        logger.info(\"CockroachDB version '{}' detected\", version);\n                    }\n                }\n            }\n\n            databaseType = databaseTypeMappings.getProperty(databaseProductName);\n            if (databaseType == null) {\n                throw new FlowableException(\"couldn't deduct database type from database product name '\" + databaseProductName + \"'\");\n            }\n            logger.debug(\"using database type: {}\", databaseType);\n\n        } catch (SQLException e) {\n            throw new RuntimeException(\"Exception while initializing Database connection\", e);\n        } finally {\n            try {\n                if (connection != null) {\n                    connection.close();\n                }\n            } catch (SQLException e) {\n                logger.error(\"Exception while closing the Database connection\", e);\n            }\n        }\n\n        return databaseType;\n    }\n\n}\n","sourceCodeStart":98,"sourceCodeEnd":131,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/util/DbUtil.java#L98-L131","documentation":"DbUtil.determineDatabaseType wraps any SQLException raised while querying database metadata (getting the connection or its product name) into a RuntimeException with message 'Exception while initializing Database connection', preserving the cause.","triggerScenarios":"Engine startup when the JDBC connection cannot be established: wrong host/port, bad credentials, database down, network/firewall blocking, or driver failure during getConnection or metadata retrieval.","commonSituations":"Database not yet started in Docker-compose order; wrong jdbc username/password; DB behind firewall; DNS resolution failure at boot.","solutions":["Read the wrapped cause (e.getCause()) to see the actual SQLException","Verify jdbc url, credentials, and that the database is reachable (try connecting with a CLI/client)","Ensure the database container/service is started before the Flowable engine initializes","Check network/DNS/firewall between the app and the database"],"exampleFix":"// before\njdbcUrl=jdbc:postgresql://db-host:5432/flowable\n// after  (verify host/port & db running)\n# psql -h db-host -p 5432 -U flowable -d flowable\njdbcUrl=jdbc:postgresql://localhost:5432/flowable","handlingStrategy":"try-catch","validationCode":"try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {\n    // connectivity probe before engine init\n} catch (SQLException e) {\n    logger.error(\"Database unreachable at startup: {}\", e.getMessage());\n}","typeGuard":null,"tryCatchPattern":"try {\n    engineConfig.buildEngine();\n} catch (RuntimeException e) {\n    if (\"Exception while initializing Database connection\".equals(e.getMessage())) {\n        logger.error(\"DB init failed, root cause: {}\", e.getCause(), e.getCause());\n    }\n}","preventionTips":["Always inspect getCause() for the real SQLException","Add readiness/health checks so the app starts only after the DB is up","Validate jdbc url/credentials in a smoke test before engine boot"],"tags":["flowable","database","jdbc","connection","startup"],"backgroundTag":"connection-refused","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"}