{"record":{"id":"1d438f8b3462e58f","repo":"apache/pulsar","slug":"entry-filter-name-cannot-be-loaded-see-the-b","errorCode":null,"errorMessage":"Entry filter `${name}` cannot be loaded, see the broker logs for further details","messagePattern":"Entry filter `(.+?)` cannot be loaded, see the broker logs for further details","errorType":"exception","errorClass":"java.lang.RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/plugin/EntryFilterProvider.java","lineNumber":197,"sourceCode":"        }\n\n        return ObjectMapperFactory.getYamlMapper().reader().readValue(\n                configStr, EntryFilterDefinition.class\n        );\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    protected EntryFilter load(EntryFilterMetaData metadata)\n            throws IOException {\n        final EntryFilterDefinition def = metadata.getDefinition();\n        if (StringUtils.isBlank(def.getEntryFilterClass())) {\n            throw new RuntimeException(\"Entry filter `\" + def.getName() + \"` does NOT provide a entry\"\n                    + \" filters implementation\");\n        }\n        try {\n            final NarClassLoader ncl = getNarClassLoader(metadata.getArchivePath());\n            if (ncl == null) {\n                throw new RuntimeException(\"Entry filter `\" + def.getName() + \"` cannot be loaded, \"\n                        + \"see the broker logs for further details\");\n            }\n            Class entryFilterClass = ncl.loadClass(def.getEntryFilterClass());\n            Object filter = entryFilterClass.getDeclaredConstructor().newInstance();\n            if (!(filter instanceof EntryFilter)) {\n                throw new IOException(\"Class \" + def.getEntryFilterClass()\n                        + \" does not implement entry filter interface\");\n            }\n            EntryFilter pi = (EntryFilter) filter;\n            // the classloader is shared with the broker, the instance doesn't own it\n            return new EntryFilterWithClassLoader(pi, ncl, false);\n        } catch (Throwable e) {\n            if (e instanceof IOException) {\n                throw (IOException) e;\n            }\n            log.error()\n                    .attr(\"entryFilterClass\", metadata.getDefinition().getEntryFilterClass())\n                    .exception(e)","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/plugin/EntryFilterProvider.java#L179-L215","documentation":"After resolving the filter definition, load() obtains a NarClassLoader for the archive path. If getNarClassLoader returns null (the archive could not be opened/loaded; details are logged), the provider throws a RuntimeException pointing the user to broker logs.","triggerScenarios":"load() called with metadata whose archivePath is null, nonexistent, unreadable, or whose NAR failed classloader construction.","commonSituations":"NAR file deleted or moved after policy set; wrong permissions on the entryFilters directory; broker running in container without the NAR volume mounted; corrupted NAR upload.","solutions":["Check broker logs at ERROR level for the underlying NAR load failure","Confirm the archive file exists and is readable at metadata.getArchivePath() on this broker","Redeploy the NAR to the entryFiltersDirectory and restart the broker"],"exampleFix":"// before\nNAR missing: /pulsar/entryfilters/ (empty directory)\n// after\ncp audit-filter.nar /pulsar/entryfilters/ && chown pulsar:pulsar /pulsar/entryfilters/audit-filter.nar && restart broker","handlingStrategy":"try-catch","validationCode":"Path archive = Path.of(metadata.getArchivePath());\nif (!Files.isRegularFile(archive) || !Files.isReadable(archive)) {\n    throw new IllegalStateException(\"Filter NAR missing/unreadable: \" + archive);\n}","typeGuard":null,"tryCatchPattern":"try {\n    EntryFilter f = provider.load(metadata);\n} catch (RuntimeException e) {\n    log.error(\"NAR load failed for {}; inspect broker logs for the root cause\", metadata.getArchivePath(), e);\n}","preventionTips":["Verify NAR presence/readability in the entryFiltersDirectory after each deploy","Mount the NAR volume in containerized brokers","Watch broker ERROR logs at startup for NAR classloader failures"],"tags":["pulsar","entry-filter","nar-loading","classpath"],"backgroundTag":"plugin-archive-load-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}