quarkusio/quarkus · error · ConfigurationException

The application is using a Stork Consul provider but does no

Error message

The application is using a Stork Consul provider but does not depend on the `quarkus-jackson` extension. The Vert.x Consul client requires Jackson for JSON serialization. Without it, the application will fail at runtime with a NoClassDefFoundError. Add the `io.quarkus:quarkus-jackson` extension to the project.

What it means

This build-time check in SmallRyeStorkProcessor fails the Quarkus build when the application includes the Stork Consul provider (detected via QuarkusClassLoader.isClassPresentAtRuntime of the Consul discovery or registrar provider classes) but the quarkus-jackson capability is absent. The Vert.x Consul client that Stork delegates to serializes Consul catalog/KV payloads with Jackson, so without the extension the app compiles but crashes at runtime with NoClassDefFoundError. Quarkus surfaces it early as a ConfigurationException during deployment.

Source

Thrown at extensions/smallrye-stork/deployment/src/main/java/io/quarkus/stork/deployment/SmallRyeStorkProcessor.java:108

                                "\n - with Apache Maven, run: `./mvnw quarkus:add-extension -Dextensions=\"io.quarkus:quarkus-kubernetes-client\"`"
                                +
                                "\n - or just add the `io.quarkus:quarkus-kubernetes-client` dependency to the project");
            }
        }
    }

    /**
     * This build step is the fix for <a href="https://github.com/quarkusio/quarkus/issues/54121">#54121</a>.
     * The Vert.x Consul client requires Jackson for JSON serialization. When a Consul Stork provider
     * (service discovery or service registration) is on the classpath without the {@code quarkus-jackson}
     * extension, the application fails at runtime with a cryptic {@code NoClassDefFoundError}.
     */
    @BuildStep
    @Produce(AlwaysBuildItem.class)
    void checkThatJacksonExtensionIsUsedWhenConsulIsOnTheClasspath(Capabilities capabilities) {
        if (isConsulPresentAtRuntime()) {
            if (!capabilities.isPresent(Capability.JACKSON)) {
                throw new ConfigurationException(
                        "The application is using a Stork Consul provider but does not depend on the `quarkus-jackson` extension."
                                + " The Vert.x Consul client requires Jackson for JSON serialization."
                                + " Without it, the application will fail at runtime with a NoClassDefFoundError."
                                + " Add the `io.quarkus:quarkus-jackson` extension to the project.");
            }
        }
    }

    @BuildStep
    @Record(ExecutionTime.RUNTIME_INIT)
    @Consume(AlwaysBuildItem.class)
    @Consume(SyntheticBeansRuntimeInitBuildItem.class)
    @Consume(StorkRegistrationConfigReadyBuildItem.class)
    @Produce(StorkInitializedBuildItem.class)
    void initializeStork(SmallRyeStorkRecorder storkRecorder, ShutdownContextBuildItem shutdown, VertxBuildItem vertx) {
        storkRecorder.initialize(shutdown, vertx.getVertx());
    }

View on GitHub (pinned to e1c734241f)

Solutions

Add the io.quarkus:quarkus-jackson extension to the project's build file (pom.xml dependencies or Gradle dependencies).
Verify with ./mvnw dependency:tree that quarkus-jackson is resolved once the Stork Consul artifacts are present.
If Consul was included by mistake, remove the stork-service-discovery-consul / consul registrar dependency and use a different Stork load-balancer/discovery type in configuration.

Example fix

// before (pom.xml)
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-smallrye-stork</artifactId>
</dependency>

// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-smallrye-stork</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jackson</artifactId>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// pom.xml / build.gradle check before building
// Maven: ./mvnw dependency:tree -Dincludes=io.quarkus:quarkus-jackson
// fails/empty output means the extension is missing while stork-service-discovery-consul is present

Prevention

Always add quarkus-jackson alongside any Stork Consul dependency
Prefer the quarkus-smallrye-stork extension route over raw smallrye-stork artifacts so capabilities are declared
Run a full build (not -Dquickly) in CI to catch ConfigurationException early

When it happens

Trigger: Building a Quarkus app whose dependencies include io.smallrye.stork:stork-service-discovery-consul (or the Consul registrar artifact) while no dependency brings the Capability.JACKSON capability — e.g. only quarkus-rest-client-jackson is omitted and no other extension pulls in quarkus-jackson.

Common situations: Adding a smallrye-stork consul dependency directly in pom.xml without its Quarkus extension wrapper; migrating from Eureka/static-list Stork configs to Consul; trimming 'unused' extensions quarkus-jackson that was transitively present before; using Gradle/BOM updates that dropped the transitive jackson 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/d482b117c378ae87. Report an issue: GitHub.