quarkusio/quarkus · error · CodeGenException

Unable to find the following conversion class: ${customConve

Error message

Unable to find the following conversion class: ${customConversion}

What it means

The Avro code-gen accepts custom conversion classes (quarkus.avro.codegen.custom-conversions). Each configured class name is loaded with Class.forName at build time; if the class is not on the build classpath, this CodeGenException is thrown. Note the check conversionClass.isInstance(Conversions.UUIDConversion.class) is inverted-looking, but the thrown error only concerns the class not being found.

Source

Thrown at extensions/avro/deployment/src/main/java/io/quarkus/avro/deployment/AvroSchemaCodeGenProvider.java:78

        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.addCustomConversion(Conversions.UUIDConversion.class);

        for (String customConversion : options.customConversions) {
            try {
                Class<?> conversionClass = Class.forName(customConversion);
                if (!conversionClass.isInstance(Conversions.UUIDConversion.class)) {
                    compiler.addCustomConversion(conversionClass);
                }
            } catch (ClassNotFoundException e) {
                throw new CodeGenException("Unable to find the following conversion class: " + customConversion, e);
            }
        }

        try {
            compiler.compileToDestination(file, outputDirectory.toFile());
        } catch (IOException e) {
            throw new CodeGenException("Failed to copy compiled files to output directory " +
                    outputDirectory.toAbsolutePath(), e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the fully-qualified class name in quarkus.avro.codegen.custom-conversions
2. Add the artifact containing the conversion class as a compile-scope dependency of the application
3. Confirm the class is public with a public no-arg constructor and implements org.apache.avro.Conversion
4. Rebuild after dependency changes (mvn clean install) so the updated classpath is used

Example fix

// before
quarkus.avro.codegen.custom-conversions=com.example.MyConversion
// class actually at com.example.avro.MyConversion
// after
quarkus.avro.codegen.custom-conversions=com.example.avro.MyConversion

String cls = "com.example.avro.MyConversion";
try {
    Class<?> c = Class.forName(cls);
    if (!org.apache.avro.Conversion.class.isAssignableFrom(c)) {
        throw new IllegalArgumentException(cls + " is not an org.apache.avro.Conversion");
    }
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Conversion class not on classpath: " + cls);
}

try {
    project.build();
} catch (CodeGenException e) {
    if (e.getCause() instanceof ClassNotFoundException cnfe) {
        log.error("Check quarkus.avro.codegen.custom-conversions entries: " + cnfe.getMessage());
    }
    throw e;
}

When it happens

Trigger: quarkus.avro.codegen.custom-conversions lists a class name that is misspelled, in a module not on the compile classpath, or removed in a dependency upgrade.

Common situations: Typo in fully-qualified class name; conversion class lives in a test or optional dependency not visible to the deployment build; package renamed after an Avro/Quarkus upgrade.

Related errors

• Unable to find or load top command: <className>
• Failed to list matching files in ${importPath}
• Failed to compile avro IDL file: ${filePath} to Java
• Failed to compile avro protocole file: ${filePath} to Java
• Failed to copy compiled files to output directory ${outputDi

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