quarkusio/quarkus · error · CodeGenException

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

Error message

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

What it means

Quarkus Avro's IDL code generator wraps IOException from the Avro IDL compiler (org.apache.avro.idl.IDLCompiler / Compiler) when compiling a .avdl file to Java during code-gen phase. It signals that the Avro IDL file could not be read or parsed/compiled successfully. The underlying cause is chained in the CodeGenException.

Source

Thrown at extensions/avro/deployment/src/main/java/io/quarkus/avro/deployment/AvroIDLCodeGenProvider.java:56

            if (protocol != null) {
                compiler = new SpecificCompiler(protocol);
            } else {
                compiler = new SpecificCompiler(idlFile.getNamedSchemas().values());
            }

            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(), outputDir.toFile());
        } catch (IOException e) {
            throw new CodeGenException("Failed to compile avro IDL file: " + filePath.toString() + " to Java", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the chained 'Caused by' exception for the exact IDL parse error and fix the .avdl syntax at the reported line
2. Verify the .avdl file is valid with Avro's standalone tools (avro-tools/idl) outside Maven
3. Check imports/protocol references in the IDL resolve to files in the same source directory
4. Confirm file read permissions and UTF-8 encoding of the .avdl file

Example fix

// before (broken IDL)
protocol MyProto {
  record User { string name; int age }
  // missing closing brace for record
}
// after
protocol MyProto {
  record User { string name; int age; }
}

// before build, sanity-check IDL files
Files.walk(Path.of("src/main/avro")).filter(p -> p.toString().endsWith(".avdl")).forEach(p -> {
    try { new org.apache.avro.idl.IdlFile(p).compile(); }
    catch (Exception e) { throw new IllegalStateException("Invalid IDL: " + p + ": " + e.getMessage(), e); }
});

try {
    project.build();
} catch (CodeGenException e) {
    Throwable cause = e.getCause(); // inspect actual IDL parse error
    log.error("Avro IDL compile failed: " + (cause != null ? cause.getMessage() : e.getMessage()));
}

When it happens

Trigger: Running './mvnw compile' (or Quarkus dev mode) with an .avdl file under src/main/avro whose content fails IDL parsing, references unknown imports/protocols, or whose file cannot be read from disk.

Common situations: Syntax errors in the .avdl IDL; missing @namespace or unresolved imports; unreadable file due to permissions or wrong encoding; Avro version incompatibility with newer IDL syntax.

Related errors

• Failed to list matching files in ${importPath}
• Failed to compile avro protocole file: ${filePath} to Java
• Unable to find the following conversion class: ${customConve
• Failed to copy compiled files to output directory ${outputDi
• Unable to create new instance for ${clazz}

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