What causes "Failed to compile avro protocole file: ${filePath} to Java" in quarkusio/quarkus?

Inspect the chained cause for the JSON/protocol parse error and fix the .avpr file

quarkusio/quarkus · error · CodeGenException

Failed to compile avro protocole file: ${filePath} to Java

Error message

Failed to compile avro protocole file: ${filePath} to Java

What it means

Same as the IDL failure but for Avro protocol (.avpr) files: the Quarkus Avro deployment wraps IOException thrown by the Avro protocol compiler when turning a .avpr file into Java classes. The file could not be parsed as a valid Avro protocol or read from disk.

Source

Thrown at extensions/avro/deployment/src/main/java/io/quarkus/avro/deployment/AvroProtocolCodeGenProvider.java:51

    void compileSingleFile(Path filePath,
            Path outputDirectory,
            AvroOptions options) throws CodeGenException {
        try {
            final Protocol protocol = Protocol.parse(filePath.toFile());
            final SpecificCompiler compiler = new SpecificCompiler(protocol);
            compiler.setTemplateDir(templateDirectory);
            compiler.setStringType(options.stringType);
            compiler.setFieldVisibility(SpecificCompiler.FieldVisibility.PRIVATE);
            compiler.setCreateOptionalGetters(options.createOptionalGetters);
            compiler.setGettersReturnOptional(options.gettersReturnOptional);
            compiler.setOptionalGettersForNullableFieldsOnly(options.optionalGettersForNullableFieldsOnly);
            compiler.setCreateSetters(options.createSetters);
            compiler.setEnableDecimalLogicalType(options.enableDecimalLogicalType);

            compiler.setOutputCharacterEncoding("UTF-8");
            compiler.compileToDestination(filePath.toFile(), outputDirectory.toFile());
        } catch (IOException e) {
            throw new CodeGenException("Failed to compile avro protocole file: " + filePath.toString() + " to Java", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Inspect the chained cause for the JSON/protocol parse error and fix the .avpr file
Validate the .avpr parses as a valid Avro protocol JSON (e.g. with avro-tools or a JSON linter)
Ensure the file is a protocol (has 'protocol', 'types', 'messages') not a plain schema
Check file permissions/encoding

Example fix

// before (invalid: missing protocol wrapper)
{"type":"record","name":"User","fields":[{"name":"id","type":"string"}]}
// after
{"protocol":"MyProto","types":[{"type":"record","name":"User","fields":[{"name":"id","type":"string"}]}],"messages":{}}

Defensive patterns

Strategy: validation

Validate before calling

// validate .avpr is parseable JSON protocol before build
String json = Files.readString(Path.of("src/main/avro/My.avpr"));
if (!json.trim().startsWith("{") || !json.contains("\"protocol\"")) {
    throw new IllegalArgumentException("Not a valid Avro protocol file");
}

Try / catch

try {
    project.build();
} catch (CodeGenException e) {
    log.error("Avro protocol compile failed: " + e.getCause(), e);
}

Prevention

Lint .avpr files as JSON in CI
Ensure .avpr files are protocols, not schemas
Validate with avro-tools protoc compile locally
Use UTF-8 without BOM for protocol files

When it happens

Trigger: Code-gen phase encounters a .avpr file under src/main/avro that is malformed JSON, not a valid protocol object, or unreadable.

Common situations: Hand-edited .avpr with JSON syntax errors; file is actually a schema, not a protocol; truncated/invalid UTF-8 file; wrong file placed in the avro source dir.

Related errors

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