quarkusio/quarkus · error · CodeGenException

Failed to find Quarkus gRPC protoc plugin among dependencies

Error message

Failed to find Quarkus gRPC protoc plugin among dependencies

What it means

Quarkus wraps the io.quarkus:quarkus-grpc-protoc-plugin:shaded:jar artifact into a shell/cmd wrapper script so protoc can invoke the Quarkus codegen plugin. prepareQuarkusGrpcExecutable throws this CodeGenException when findArtifactPath cannot locate that exact GAV with the 'shaded' classifier among the application's dependencies.

Source

Thrown at extensions/grpc/codegen/src/main/java/io/quarkus/grpc/codegen/GrpcCodeGen.java:577

            case x86 -> "x86_32";
            case arm -> "arm_32";
            case aarch64 -> "aarch_64";
            case mips -> "mips_32";
            case mipsel -> "mipsel_32";
            case mips64 -> "mips_64";
            case mips64el -> "mipsel_64";
            case ppc32 -> "ppc_32";
            case ppc32le -> "ppcle_32";
            case ppc -> "ppc_64";
            case ppcle -> "ppcle_64";
            default -> null;
        };
    }

    private static Path prepareQuarkusGrpcExecutable(ApplicationModel appModel, Path buildDir) throws CodeGenException {
        Path pluginPath = findArtifactPath(appModel, "io.quarkus", "quarkus-grpc-protoc-plugin", "shaded", "jar");
        if (pluginPath == null) {
            throw new CodeGenException("Failed to find Quarkus gRPC protoc plugin among dependencies");
        }

        if (OS.current() != OS.WINDOWS) {
            return writeScript(buildDir, pluginPath, "#!/bin/sh\n", ".sh");
        } else {
            return writeScript(buildDir, pluginPath, "@echo off\r\n", ".cmd");
        }
    }

    private static Path writeScript(Path buildDir, Path pluginPath, String shebang, String suffix) throws CodeGenException {
        Path script;
        try {
            script = Files.createTempFile(buildDir, "quarkus-grpc", suffix);
            try (BufferedWriter writer = Files.newBufferedWriter(script)) {
                writer.write(shebang);
                writePluginExeCmd(pluginPath, writer);
            }
        } catch (IOException e) {

View on GitHub (pinned to e1c734241f)

Solutions

Ensure the quarkus-grpc extension dependency (io.quarkus:quarkus-grpc) is present and not excluded, so the shaded protoc plugin is pulled in transitively
Check exclusions/dependencyManagement are not dropping the 'shaded' classifier artifact
Inspect resolved dependencies (mvn dependency:tree or gradle dependencies) for io.quarkus:quarkus-grpc-protoc-plugin:shaded
Align the Quarkus BOM version with the extension version (use the Quarkus platform BOM) so managed coordinates match

Example fix

// before
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-grpc</artifactId>
  <exclusions>
    <exclusion><groupId>io.quarkus</groupId><artifactId>quarkus-grpc-protoc-plugin</artifactId></exclusion>
  </exclusions>
</dependency>
// after: remove the exclusion
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-grpc</artifactId>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// verify the shaded plugin artifact resolves before building
// mvn dependency:tree -Dincludes=io.quarkus:quarkus-grpc-protoc-plugin
boolean present = resolvedDependencies.stream().anyMatch(d ->
    "io.quarkus".equals(d.groupId) && "quarkus-grpc-protoc-plugin".equals(d.artifactId) && "shaded".equals(d.classifier));
if (!present) throw new IllegalStateException("quarkus-grpc-protoc-plugin (shaded) missing from dependency graph");

Try / catch

try {
    build.run();
} catch (CodeGenException e) {
    if (e.getMessage().contains("Failed to find Quarkus gRPC protoc plugin")) {
        throw new IllegalStateException("Add/keep io.quarkus:quarkus-grpc without exclusions so the shaded protoc plugin resolves", e);
    }
}

Prevention

Never exclude io.quarkus:quarkus-grpc-protoc-plugin from the quarkus-grpc dependency
Keep dependencyManagement aligned with the Quarkus platform BOM
Check dependency:tree after upgrading Quarkus to confirm the shaded classifier still resolves
Ensure corporate repositories proxy/mirror the shaded classifier artifacts

When it happens

Trigger: Running gRPC code generation where the application model lacks io.quarkus:quarkus-grpc-protoc-plugin with classifier 'shaded' and type 'jar' — typically caused by dependency exclusions, a dependencyManagement override changing the classifier/version, or a custom platform BOM not importing it.

Common situations: Corporate dependency whitelists excluding quarkus artifacts; hand-rolled quarkus-bom versions missing the plugin; Gradle/Maven builds that filter quarkus deployment/runtime dependencies; using a very old or very new Quarkus version where plugin coordinates changed.

Related errors

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