quarkusio/quarkus · error · IllegalArgumentException

@OpenApiFilter '%s' references unknown document names: %s

Error message

@OpenApiFilter '%s' references unknown document names: %s

What it means

The SmallRyeOpenApiFiltersProcessor validates @OpenApiFilter annotations at build time. Each filter's 'documents' attribute must reference document names that exist in the configuration (quarkus.smallrye-openapi.documents.*). If a filter names a document that is not configured, the build fails with this IllegalArgumentException.

Source

Thrown at extensions/smallrye-openapi/deployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiFiltersProcessor.java:131

                        .add(documentName);
            }
        }

        if (!problematicDocumentNames.isEmpty()) {
            Set<String> validDocumentNamesValues = new HashSet<>(config.documents().keySet());
            validDocumentNamesValues.add(OpenApiFilter.FILTER_RUN_FOR_ANY_DOCUMENT);

            String message = """
                    Following instances of the OpenApiFilter annotation are invalid because of a misconfigured documentNames value.
                    Valid values are: %s
                    """
                    .formatted(validDocumentNamesValues);
            message += problematicDocumentNames.entrySet().stream()
                    .map(entry -> String.format("@OpenApiFilter '%s' references unknown document names: %s",
                            entry.getKey(),
                            entry.getValue()))
                    .collect(Collectors.joining("; "));
            throw new IllegalArgumentException(message);
        }
    }

    @BuildStep
    DocumentFiltersBuildItem produceFilters(SmallRyeOpenApiConfig smallRyeOpenApiConfig,
            OpenApiFilteredIndexViewBuildItem openApiFilteredIndexViewBuildItem) {
        Set<String> allDocumentNames = smallRyeOpenApiConfig.documents().keySet();
        IndexView index = openApiFilteredIndexViewBuildItem.getIndex();

        Comparator<AnnotationInstance> comparator = Comparator
                .<AnnotationInstance, Integer> comparing(x -> x.valueWithDefault(index, "priority").asInt())
                .reversed();

        Set<AnnotationInstance> allFilterInstances = index
                .getAnnotations(NAME_OPEN_API_FILTER_ANNOTATION)
                .stream()
                .filter(ai -> ai.target().asClass().interfaceNames().contains(NAME_OAS_FILTER))
                .sorted(comparator)

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the missing document name to your config, e.g. quarkus.smallrye-openapi.documents."internal".properties-schema... or define quarkus.smallrye-openapi.documents."<name>"
2. Fix the documents value in the @OpenApiFilter annotation to match configured document names exactly
3. Check the valid names listed in the error message (it enumerates validDocumentNamesValues)

Example fix

// before
@OpenApiFilter(Filter.class, documents = {"prod", "intenal"})
// after (add config or fix typo)
@OpenApiFilter(Filter.class, documents = {"prod", "internal"})

Set<String> valid = config.documents().keySet(); // quarkus.smallrye-openapi.documents.*
for (String d : filter.documents()) { if (!valid.contains(d)) throw new IllegalArgumentException("Unknown document: " + d); }

When it happens

Trigger: Declaring an @OpenApiFilter annotation whose documents attribute contains a name not defined under quarkus.smallrye-openapi.<name>.documents or quarkus.smallrye-openapi.documents config; renaming/removing a document config entry without updating the annotation.

Common situations: Typo in document name; adding @OpenApiFilter before adding the corresponding documents config; refactoring multi-document setups and forgetting to sync annotation values.

Related errors

• quarkus.smallrye-openapi.path and quarkus.swagger-ui.path wa
• Build step '%s' does not produce any build item and thus wil
• Cannot consume/produce interface or abstract class build ite
• Failed to load application configuration
• Failed to initialize application configuration

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