YunaiV/yudao-cloud · critical · RuntimeException

Exception while initializing Database connection

Error message

Exception while initializing Database connection

What it means

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.

Source

Thrown at sql/dm/flowable-patch/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java:527

                    if (resultSet.next()) {
                        version = resultSet.getString("version");
                    }

                    if (StringUtils.isNotEmpty(version) && version.toLowerCase().startsWith(PRODUCT_NAME_CRDB.toLowerCase())) {
                        databaseProductName = PRODUCT_NAME_CRDB;
                        logger.info("CockroachDB version '{}' detected", version);
                    }
                }
            }

            databaseType = databaseTypeMappings.getProperty(databaseProductName);
            if (databaseType == null) {
                throw new FlowableException("couldn't deduct database type from database product name '" + databaseProductName + "'");
            }
            logger.debug("using database type: {}", databaseType);

        } catch (SQLException e) {
            throw new RuntimeException("Exception while initializing Database connection", e);
        } finally {
            try {
                if (connection != null) {
                    connection.close();
                }
            } catch (SQLException e) {
                logger.error("Exception while closing the Database connection", e);
            }
        }

        // Special care for MSSQL, as it has a hard limit of 2000 params per statement (incl bulk statement).
        // Especially with executions, with 100 as default, this limit is passed.
        if (DATABASE_TYPE_MSSQL.equals(databaseType)) {
            maxNrOfStatementsInBulkInsert = DEFAULT_MAX_NR_OF_STATEMENTS_BULK_INSERT_SQL_SERVER;
        }
    }

    public void initSchemaManager() {

View on GitHub (pinned to 477be9dd49)

Solutions

1. Read the chained SQLException for the root cause (socket reset, ORA-/DM- error code).
2. Verify the database is up and reachable from the app container: same host/port, no NAT timeout.
3. Enable pool validation (testOnBorrow / validation query) if a dead pooled connection is suspected.
4. Add a startup readiness probe / retry so the engine builds only after the DB accepts queries.

// readiness gate before engine build
boolean dbReady = false;
for (int i = 0; i < 30 && !dbReady; i++) {
    try (Connection c = DriverManager.getConnection(url, u, p);
         ResultSet rs = c.createStatement().executeQuery("SELECT 1")) {
        dbReady = rs.next();
    } catch (SQLException e) { Thread.sleep(1000); }
}
if (!dbReady) throw new IllegalStateException("DB not ready");

try { engine = cfg.buildProcessEngine(); }
catch (RuntimeException e) {
    if (e.getMessage().contains("initializing Database connection") && e.getCause() instanceof SQLException sql) {
        // transient: retry with backoff; permanent (auth): fail with cause
        if ("08S01".equals(sql.getSQLState())) return retryLater(cfg);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• couldn't lookup datasource from {}: {}
• couldn't deduct database type from database product name '{}
• invalid command interceptor chain configuration: {}
• Error while building ibatis SqlSessionFactory: {}
• Cannot determine the Oracle database version number

AI-assisted analysis of YunaiV/yudao-cloud@477be9dd49 (2026-08-14). Data as JSON: /api/errors/901613d065621f38. Report an issue: GitHub.