quarkusio/quarkus · error · IllegalArgumentException

Unable to implement${interface} because it is not known - pl

Error message

Unable to implement${interface} because it is not known - please make sure it's part of the Quarkus index

What it means

During Spring Data JPA augmentation, Quarkus generates an implementation for each custom fragment interface declared by a repository. This error is thrown when the fragment interface itself cannot be found in the application's Jandex index, so Quarkus cannot inspect its methods to generate forwarding code. It means the interface is not visible to the build-time index.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/generate/FragmentMethodsAdder.java:43

    private final Consumer<String> fragmentImplClassResolvedCallback;
    private final IndexView index;

    public FragmentMethodsAdder(Consumer<String> fragmentImplClassResolvedCallback, IndexView index) {
        this.fragmentImplClassResolvedCallback = fragmentImplClassResolvedCallback;
        this.index = index;
    }

    public void add(ClassCreator classCreator, String generatedClassName,
            List<DotName> customInterfaceNamesToImplement, Map<String, FieldDesc> customImplNameToHandle,
            Set<String> existingMethods) {
        for (DotName customInterfaceToImplement : customInterfaceNamesToImplement) {
            String customImplementationClassName = FragmentMethodsUtil
                    .getImplementationDotName(customInterfaceToImplement, index).toString();
            fragmentImplClassResolvedCallback.accept(customImplementationClassName);

            ClassInfo customInterfaceToImplementClassInfo = index.getClassByName(customInterfaceToImplement);
            if (customInterfaceToImplementClassInfo == null) {
                throw new IllegalArgumentException("Unable to implement" + customInterfaceToImplement
                        + " because it is not known - please make sure it's part of the Quarkus index");
            }

            for (MethodInfo methodToImplement : customInterfaceToImplementClassInfo.methods()) {
                // methods defined on the interface are implemented by forwarding them to the bean that implements them

                String[] methodParameterTypes = new String[methodToImplement.parametersCount()];
                for (int i = 0; i < methodToImplement.parametersCount(); i++) {
                    methodParameterTypes[i] = methodToImplement.parameterType(i).name().toString();
                }

                String methodReturnType = methodToImplement.returnType().name().toString();
                String methodKey = GenerationUtil.methodKey(methodToImplement.name(), methodReturnType,
                        methodParameterTypes);

                if (!existingMethods.contains(methodKey)) {
                    // Build the MethodTypeDesc
                    MethodTypeDesc mtd = GenerationUtil.toMethodTypeDesc(methodReturnType, methodParameterTypes);

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the fragment interface is in the application project (indexed source) rather than an external JAR
2. If the interface is in a dependency JAR, add a META-INF/jandex.idx to that JAR or register the JAR for indexing in the Quarkus build plugin (quarkus.index-dependency.*)
3. Run a clean rebuild to refresh the Jandex index
4. Verify the repository's generic signature references the exact interface name available on the classpath

Example fix

// pom.xml of a library containing fragment interfaces
<plugin>
  <groupId>io.smallrye</groupId>
  <artifactId>jandex-maven-plugin</artifactId>
  <executions><execution><id>make-index</id><goals><goal>jandex</goal></goals></execution></executions>
</plugin>

// In a test or build check: ensure fragment interfaces are application classes
assert new java.io.File("src/main/java/com/example/PersonRepositoryCustom.java").exists();
// For external JARs, verify index exists:
// unzip -l libs/my-fragments.jar | grep META-INF/jandex.idx

When it happens

Trigger: A repository extends a custom fragment interface (e.g. MyRepositoryCustom) that is not indexed: the interface lives in a dependency JAR not indexed by Quarkus, is in a source folder excluded from indexing, or its name/class referenced by the repository was compiled outside the application index.

Common situations: Fragment interfaces placed in a separate un-indexed library module; using a compiled-only dependency without a Jandex INDEX.LST; IDE stale builds; moving interfaces to a package ignored by the Quarkus index.

Related errors

• Entity ${entity} was not part of the Quarkus index
• Method ${repositoryMethodDescription} cannot be parsed. Did
• Return type of method ${methodName} of Repository ${reposito
• ${t.name()} is not in the Quarkus Jandex index and cannot be
• spEL expressions are not currently supported. Offending meth

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