quarkusio/quarkus · error · RuntimeException

Failed to find any non-blocking provider for startup actions

Error message

Failed to find any non-blocking provider for startup actions. Either import the quarkus-vertx module, or do not declare non-blocking startup actions.

What it means

NonBlockingSupport.subscribeAndAwait throws RuntimeException when the static PROVIDER is null, meaning the Quarkus Vert.x extension is not on the classpath so no NonBlockingProvider was registered. Non-blocking startup actions require a Vert.x-based event-loop provider to subscribe to the Uni and block for its result.

Source

Thrown at extensions/arc/runtime/src/main/java/io/quarkus/arc/runtime/NonBlockingSupport.java:39

        ServiceLoader<NonBlockingProvider> loader = ServiceLoader.load(NonBlockingProvider.class);
        Optional<NonBlockingProvider> first = loader.findFirst();
        if (first.isEmpty()) {
            PROVIDER = null;
        } else {
            PROVIDER = first.get();
        }
    }

    /**
     * Delegates this call to the declared {@link NonBlockingProvider} implementation, hopefully Quarkus Vert.x, if
     * it is available.
     *
     * @throws RuntimeException if the Quarkus Vert.x extension is not present.
     * @see NonBlockingProvider#subscribeAndAwait(Supplier)
     */
    public static <T> T subscribeAndAwait(Supplier<Uni<T>> uniSupplier) throws Throwable {
        if (PROVIDER == null) {
            throw new RuntimeException(
                    ERROR_MSG);
        }
        return PROVIDER.subscribeAndAwait(uniSupplier);
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Add the quarkus-vertx dependency to the application
Make the startup action blocking so it does not require a non-blocking provider
If authoring a library, document/require quarkus-vertx for the non-blocking path

Example fix

// before
<dependency> <!-- quarkus-vertx missing --> </dependency>
// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-vertx</artifactId>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

boolean vertxPresent;
try {
    Class.forName("io.quarkus.vertx.runtime.NonBlockingProviderImpl", false,
            Thread.currentThread().getContextClassLoader());
    vertxPresent = true;
} catch (ClassNotFoundException e) { vertxPresent = false; }

Try / catch

try {
    NonBlockingSupport.subscribeAndAwait(uniSupplier);
} catch (RuntimeException e) {
    logger.error("Add io.quarkus:quarkus-vertx or make the startup action blocking", e);
}

Prevention

Add quarkus-vertx whenever you use non-blocking startup actions
Audit dependencies after upgrades to ensure quarkus-vertx was not dropped transitively
Prefer blocking startup actions in extensions that do not require Vert.x

When it happens

Trigger: Declaring a startup action/bean method as non-blocking (e.g. @NonBlocking / returning Uni via NonBlockingProvider helpers) while the application does not include the quarkus-vertx module.

Common situations: Removing or never adding the quarkus-vertx dependency while keeping non-blocking startup logic; an extension that transitively depended on vertx was upgraded/removed; tests running without the vertx extension.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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