quarkusio/quarkus · error · CodeGenException

Unsupported OS, please use maven plugin instead to generate

Error message

Unsupported OS, please use maven plugin instead to generate Java classes from proto files

What it means

Quarkus derives the protoc OS classifier from smallrye-common OS/CPU detection. If the current OS is not LINUX, WINDOWS, or MAC (e.g. Solaris, AIX, FreeBSD, or an unknown os.name), osClassifier() throws this CodeGenException because no prebuilt protoc binaries exist for it.

Source

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

        for (ResolvedDependency artifact : model.getDependencies()) {
            if (groupId.equals(artifact.getGroupId())
                    && artifactId.equals(artifact.getArtifactId())
                    && classifier.equals(artifact.getClassifier())
                    && packaging.equals(artifact.getType())) {
                artifactPath = artifact.getResolvedPaths().getSinglePath();
            }
        }
        return artifactPath;
    }

    private String osClassifier() throws CodeGenException {
        String architecture = getArchitecture();
        return switch (OS.current()) {
            case LINUX -> "linux-" + architecture;
            case WINDOWS -> "windows-" + architecture;
            case MAC -> "osx-" + architecture;
            default -> throw new CodeGenException(
                    "Unsupported OS, please use maven plugin instead to generate Java classes from proto files");
        };
    }

    /**
     * {@return the bespoke architecture string, or {@code null} if unknown}
     */
    private static String getArchitecture() {
        return switch (CPU.host()) {
            case x64 -> "x86_64";
            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";

View on GitHub (pinned to e1c734241f)

Solutions

Build on a supported OS (Linux, macOS, Windows) or in a Linux container (e.g. via Docker) instead of the host OS
Generate the Java classes from proto files with the protobuf-maven-plugin (protobuf grpc) as the message suggests, then let Quarkus consume them
Generate code in a CI step on Linux and commit/check in the generated sources for unsupported local environments

Example fix

// before: building directly on unsupported OS
./mvnw clean install
// after: generate protoc classes via the maven plugin or on Linux
mvn protobuf:compile protobuf:compile-custom  # or build in a linux docker container

Defensive patterns

Strategy: fallback

Validate before calling

String os = System.getProperty("os.name", "").toLowerCase();
boolean supported = os.contains("linux") || os.contains("windows") || os.contains("mac");
if (!supported) {
    System.out.println("Unsupported OS for Quarkus gRPC codegen; generate protos with protobuf-maven-plugin or in a Linux container");
}

Try / catch

try {
    build.run();
} catch (CodeGenException e) {
    if (e.getMessage().contains("Unsupported OS")) {
        // fallback: run codegen in a Linux container and reuse generated sources
        exec("docker run -v $PWD:/ws -w /ws maven:3-eclipse-temurin mvn generate-sources");
    }
}

Prevention

Develop and build on Linux/macOS/Windows only; use Linux containers for other platforms
Pre-generate proto classes on a supported platform and commit them for exotic OSes
Use protobuf-maven-plugin on unsupported hosts as the message suggests
Check `java -XshowSettings:properties` os.name if you believe your OS is supported

When it happens

Trigger: Running Quarkus gRPC code generation on an unsupported OS, or in an environment where os.name is unrecognized (unusual JVM/OS combos, exotic containers), so the switch over OS.current() hits the default branch.

Common situations: Building on FreeBSD/Solaris/IBM i; using a container image with a modified os.name; running on z/OS or other mainframe JVMs; security-hardened JVMs that strip os properties.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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