{"record":{"id":"8f2fe31ccc15f713","repo":"quarkusio/quarkus","slug":"openapifilter-s-references-unknown-document-na","errorCode":null,"errorMessage":"@OpenApiFilter '%s' references unknown document names: %s","messagePattern":"@OpenApiFilter '(.+?)' references unknown document names: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/smallrye-openapi/deployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiFiltersProcessor.java","lineNumber":131,"sourceCode":"                        .add(documentName);\n            }\n        }\n\n        if (!problematicDocumentNames.isEmpty()) {\n            Set<String> validDocumentNamesValues = new HashSet<>(config.documents().keySet());\n            validDocumentNamesValues.add(OpenApiFilter.FILTER_RUN_FOR_ANY_DOCUMENT);\n\n            String message = \"\"\"\n                    Following instances of the OpenApiFilter annotation are invalid because of a misconfigured documentNames value.\n                    Valid values are: %s\n                    \"\"\"\n                    .formatted(validDocumentNamesValues);\n            message += problematicDocumentNames.entrySet().stream()\n                    .map(entry -> String.format(\"@OpenApiFilter '%s' references unknown document names: %s\",\n                            entry.getKey(),\n                            entry.getValue()))\n                    .collect(Collectors.joining(\"; \"));\n            throw new IllegalArgumentException(message);\n        }\n    }\n\n    @BuildStep\n    DocumentFiltersBuildItem produceFilters(SmallRyeOpenApiConfig smallRyeOpenApiConfig,\n            OpenApiFilteredIndexViewBuildItem openApiFilteredIndexViewBuildItem) {\n        Set<String> allDocumentNames = smallRyeOpenApiConfig.documents().keySet();\n        IndexView index = openApiFilteredIndexViewBuildItem.getIndex();\n\n        Comparator<AnnotationInstance> comparator = Comparator\n                .<AnnotationInstance, Integer> comparing(x -> x.valueWithDefault(index, \"priority\").asInt())\n                .reversed();\n\n        Set<AnnotationInstance> allFilterInstances = index\n                .getAnnotations(NAME_OPEN_API_FILTER_ANNOTATION)\n                .stream()\n                .filter(ai -> ai.target().asClass().interfaceNames().contains(NAME_OAS_FILTER))\n                .sorted(comparator)","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/smallrye-openapi/deployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiFiltersProcessor.java#L113-L149","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typo in document name; adding @OpenApiFilter before adding the corresponding documents config; refactoring multi-document setups and forgetting to sync annotation values.","solutions":["Add the missing document name to your config, e.g. quarkus.smallrye-openapi.documents.\"internal\".properties-schema... or define quarkus.smallrye-openapi.documents.\"<name>\"","Fix the documents value in the @OpenApiFilter annotation to match configured document names exactly","Check the valid names listed in the error message (it enumerates validDocumentNamesValues)"],"exampleFix":"// before\n@OpenApiFilter(Filter.class, documents = {\"prod\", \"intenal\"})\n// after (add config or fix typo)\n@OpenApiFilter(Filter.class, documents = {\"prod\", \"internal\"})","handlingStrategy":"validation","validationCode":"Set<String> valid = config.documents().keySet(); // quarkus.smallrye-openapi.documents.*\nfor (String d : filter.documents()) { if (!valid.contains(d)) throw new IllegalArgumentException(\"Unknown document: \" + d); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep document names in one constant set shared between config and annotations","Validate @OpenApiFilter documents values against config before building","Watch for typos — the error lists the valid names, compare them literally"],"tags":["openapi","build-time-validation","configuration"],"backgroundTag":"unknown-document-reference","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}