{"record":{"id":"54ef6bec377550af","repo":"elastic/elasticsearch","slug":"unknown-named-object-category","errorCode":null,"errorMessage":"unknown named object category [{}]","messagePattern":"unknown named object category \\[(.+?)\\]","errorType":"exception","errorClass":"XContentParseException","httpStatus":null,"severity":"error","filePath":"libs/x-content/src/main/java/org/elasticsearch/xcontent/NamedXContentRegistry.java","lineNumber":173,"sourceCode":"     */\n    public boolean hasParser(Class<?> categoryClass, String name, RestApiVersion apiVersion) {\n        final Map<Class<?>, Map<String, Entry>> versionMap = registry.get(apiVersion);\n        if (versionMap == null) {\n            return false;\n        }\n        final Map<String, Entry> parsers = versionMap.get(categoryClass);\n        return parsers != null && parsers.containsKey(name);\n    }\n\n    // scope for testing\n    public <T> Entry lookupParser(Class<T> categoryClass, String name, XContentParser parser) {\n        Map<String, Entry> parsers = registry.getOrDefault(parser.getRestApiVersion(), emptyMap()).get(categoryClass);\n        if (parsers == null) {\n            if (registry.isEmpty()) {\n                // The \"empty\" registry will never work so we throw a better exception as a hint.\n                throw new XContentParseException(\"named objects are not supported for this parser\");\n            }\n            throw new XContentParseException(\"unknown named object category [\" + categoryClass.getName() + \"]\");\n        }\n        Entry entry = parsers.get(name);\n        if (entry == null) {\n            throw new NamedObjectNotFoundException(parser.getTokenLocation(), \"unknown field [\" + name + \"]\", parsers.keySet());\n        }\n        if (false == entry.name.match(name, parser.getDeprecationHandler())) {\n            /* Note that this shouldn't happen because we already looked up the entry using the names but we need to call `match` anyway\n             * because it is responsible for logging deprecation warnings. */\n            throw new XContentParseException(\n                parser.getTokenLocation(),\n                \"unable to parse \" + categoryClass.getSimpleName() + \" with name [\" + name + \"]: parser didn't match\"\n            );\n        }\n        return entry;\n    }\n\n}\n","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/x-content/src/main/java/org/elasticsearch/xcontent/NamedXContentRegistry.java#L155-L191","documentation":"lookupParser throws when the registry is non-empty (so it isn't the empty-registry case) but the requested category class has no entry map at all for the active REST API version. This means named objects of that category are simply not registered, as opposed to a specific name being unknown.","triggerScenarios":"Requesting a named object for a category class (e.g. QueryBuilder.class, Aggregation.class) that has zero registrations in the registry for the current RestApiVersion. Mixing a category the registry was never taught about.","commonSituations":"Using a category that belongs to a different distribution/module than the one whose registry you hold. Version-skewed parsing where the category exists in a newer module not loaded. Typos in the category class passed to namedObject.","solutions":["Register the category in the NamedXContentRegistry with the appropriate Entry list, or use a registry that already includes it.","Confirm the category class passed to namedObject is the exact class the entries were registered under (subclass vs superclass mismatches cause this).","Load the module/plugin that contributes that category's named content."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// confirm the category is registered for the active REST API version\nboolean registered = registry.isRegistered(categoryClass, name); // or check getCategoryNames\nif (!registered) { /* register category or pick a registry that includes it */ }","typeGuard":null,"tryCatchPattern":"try {\n    Entry e = registry.lookupParser(categoryClass, name, parser);\n} catch (XContentParseException ex) {\n    if (ex.getMessage().startsWith(\"unknown named object category [\")) {\n        // register the category or load the contributing module\n    }\n}","preventionTips":["Pass the exact category class entries were registered under (no subclass/superclass substitution).","Load modules/plugins that contribute the named category before parsing.","Centralize registry construction so categories aren't accidentally omitted."],"tags":["xcontent","named-content","registry","category"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}