YunaiV/ruoyi-vue-pro · critical · RuntimeException

Exception while initializing Database connection

Error message

Exception while initializing Database connection

What it means

During database type detection Flowable opens a Connection, calls getMetaData(), and (for Postgres) runs 'select version()'. Any SQLException in that block is caught and rethrown as a RuntimeException with this message and the original SQLException as cause. It signals the connection itself is broken during the metadata probe.

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 0418084e22)

Solutions

1. Inspect the caused-by SQLException for SQLState/vendor code to pinpoint the failing metadata call.
2. Ensure the DB user has the necessary privileges (at least CONNECT and SELECT on system/version functions).
3. Add a connection-readiness wait before Flowable engine init.
4. Use a JDBC driver version compatible with the target DB server version.

Example fix

// before: init immediately, races with DB startup
processEngine = cfg.buildProcessEngine();
// after: wait for connectivity first
while (!dataSource.getConnection().isValid(2)) { /* readiness wait */ }
processEngine = cfg.buildProcessEngine();

try (Connection c = dataSource.getConnection()) {
    if (!c.isValid(2)) throw new IllegalStateException("DB connection not valid");
    c.getMetaData().getDatabaseProductName();
} catch (SQLException e) { throw new IllegalStateException("DB not ready", e); }

null

try { engine = cfg.buildProcessEngine(); }
catch (RuntimeException e) {
    if (e.getCause() instanceof SQLException) { /* wait for DB readiness, retry once */ }
    throw e;
}

When it happens

Trigger: The connection is invalid mid-init (closed by pool, network blip, DB still starting); the Postgres 'select version()' query fails due to permissions; metadata calls raise SQLFeatureNotSupportedException on a thin driver.

Common situations: CI races where Flowable inits before the DB accepts queries; read-only DB user lacking SELECT on version(); driver incompatibility (older driver vs newer DB) causing SQLException on metadata.

Related errors

• couldn't lookup datasource from {}: {}
• DataSource or JDBC properties have to be specified in a proc
• couldn't deduct database type from database product name '{}
• invalid command interceptor chain configuration: {}
• Error while building ibatis SqlSessionFactory: {}

AI-assisted analysis of YunaiV/ruoyi-vue-pro@0418084e22 (2026-08-14). Data as JSON: /api/errors/363b55f9e6c86816. Report an issue: GitHub.