quarkusio/quarkus · error · UnsupportedOperationException

Cannot retrieve a connection to the database during Quarkus'

Error message

Cannot retrieve a connection to the database during Quarkus' static initialization. Delay the connection retrieval until runtime.

What it means

QuarkusStaticInitConnectionProvider is used while Hibernate services are initialized during Quarkus' static (build/native-image) initialization, where no database connection can be made. Its getConnection() always throws UnsupportedOperationException with this message, meaning Hibernate attempted to obtain a JDBC connection too early — during static init instead of runtime.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusStaticInitConnectionProvider.java:12

package io.quarkus.hibernate.orm.runtime.service;

import java.sql.Connection;
import java.sql.SQLException;

import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
import org.hibernate.service.UnknownUnwrapTypeException;

public class QuarkusStaticInitConnectionProvider implements ConnectionProvider {
    @Override
    public Connection getConnection() throws SQLException {
        throw new UnsupportedOperationException(
                "Cannot retrieve a connection to the database during Quarkus' static initialization. Delay the connection retrieval until runtime.");
    }

    @Override
    public void closeConnection(Connection connection) throws SQLException {
        // Should not be called, since getting a connection is impossible.
    }

    @Override
    public boolean supportsAggressiveRelease() {
        return false;
    }

    @Override
    public boolean isUnwrappableAs(final Class<?> unwrapType) {
        return ConnectionProvider.class.equals(unwrapType);
    }

View on GitHub (pinned to e1c734241f)

Solutions

Delay the database access: move connection-requiring logic out of static initializers into runtime beans (@Startup/@Observes StartupEvent or lazy CDI injection).
For native images, ensure Hibernate is initialized at runtime (RUNTIME_INIT), not build time — avoid static fields holding SessionFactory/EntityManager.
Check schema generation settings so DDL work happens at runtime startup, not during static init.

Example fix

// before
public class DbWarmup {
    static {
        sessionFactory.openSession(); // runs during static init
    }
}

// after
@ApplicationScoped
public class DbWarmup {
    void onStart(@Observes StartupEvent ev) {
        sessionFactory.openSession(); // runs at runtime startup
    }
}

Defensive patterns

Strategy: validation

Validate before calling

// Detect DB access in static initializers before native build
// (run a build-time check)
if (isStaticInitPhase()) {
    throw new IllegalStateException("Do not acquire DB connections during static init; "
        + "move work to @Observes StartupEvent or runtime-init beans");
}

Try / catch

try {
    connection = connectionProvider.getConnection();
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("static initialization")) {
        log.error("DB access attempted during static init — defer to runtime (StartupEvent / @Transactional)");
    }
    throw e;
}

Prevention

Never open sessions/connections in static blocks or build-time-init constructors
Initialize Hibernate lazily or at runtime init (RUNTIME_INIT) in native images
Move schema generation to runtime startup rather than static init
Keep static fields free of SessionFactory/EntityManager references

When it happens

Trigger: Hibernate attempting connection acquisition during static initialization: e.g. schema generation/export or DDL validation configured to run at startup being executed during the Quarkus static-init phase, or code that triggers a JDBC connection from a static initializer of a class processed at image build time.

Common situations: Setting quarkus.hibernate-orm.database.generation=create-drop/update in a native image context that executes during static init; custom code running DB access inside static blocks or constructors captured for native image build; using features that eagerly connect at build time instead of runtime init.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/7553ac9c9c02d22a. Report an issue: GitHub.