{"record":{"id":"901613d065621f38","repo":"YunaiV/yudao-cloud","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":"sql/dm/flowable-patch/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java","lineNumber":527,"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        // Special care for MSSQL, as it has a hard limit of 2000 params per statement (incl bulk statement).\n        // Especially with executions, with 100 as default, this limit is passed.\n        if (DATABASE_TYPE_MSSQL.equals(databaseType)) {\n            maxNrOfStatementsInBulkInsert = DEFAULT_MAX_NR_OF_STATEMENTS_BULK_INSERT_SQL_SERVER;\n        }\n    }\n\n    public void initSchemaManager() {","sourceCodeStart":509,"sourceCodeEnd":545,"githubUrl":"https://github.com/YunaiV/yudao-cloud/blob/477be9dd49ab7223a972a6abdff0684d6423dec3/sql/dm/flowable-patch/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java#L509-L545","documentation":"While detecting the database type, Flowable executes metadata queries on a live connection; any SQLException (connection failure, timeout, driver error) is wrapped in this RuntimeException. Unlike errors 5 and 4, this one means the connection itself was usable at open time but failed during use, or closing/opening raised an error.","triggerScenarios":"getConnection() succeeds but SELECT version / getMetaData().getDatabaseProductName() fails: flaky network drops the socket, database restarts mid-startup, connection pool hands out a dead connection, or the version query hits a permissions error.","commonSituations":"Database not fully ready when the app starts (race in docker-compose/k8s); firewall/LB idle-killing connections; DM driver incompatibility with metadata queries; connection pool misconfigured with too-long validation interval.","solutions":["Read the chained SQLException for the root cause (socket reset, ORA-/DM- error code).","Verify the database is up and reachable from the app container: same host/port, no NAT timeout.","Enable pool validation (testOnBorrow / validation query) if a dead pooled connection is suspected.","Add a startup readiness probe / retry so the engine builds only after the DB accepts queries."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// readiness gate before engine build\nboolean dbReady = false;\nfor (int i = 0; i < 30 && !dbReady; i++) {\n    try (Connection c = DriverManager.getConnection(url, u, p);\n         ResultSet rs = c.createStatement().executeQuery(\"SELECT 1\")) {\n        dbReady = rs.next();\n    } catch (SQLException e) { Thread.sleep(1000); }\n}\nif (!dbReady) throw new IllegalStateException(\"DB not ready\");","typeGuard":null,"tryCatchPattern":"try { engine = cfg.buildProcessEngine(); }\ncatch (RuntimeException e) {\n    if (e.getMessage().contains(\"initializing Database connection\") && e.getCause() instanceof SQLException sql) {\n        // transient: retry with backoff; permanent (auth): fail with cause\n        if (\"08S01\".equals(sql.getSQLState())) return retryLater(cfg);\n    }\n    throw e;\n}","preventionTips":["Use container healthchecks/readiness probes so the app starts only when the DB accepts queries","Enable connection validation (testOnBorrow) in pools feeding Flowable"],"tags":["flowable","database","connection","sql","startup"],"backgroundTag":null,"analyzedSha":"477be9dd49ab7223a972a6abdff0684d6423dec3","analyzedAt":"2026-08-14T13:35:31.121Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}