apache/pulsar · error · org.apache.pulsar.broker.service.plugin.InvalidEntryFilterException

Entry filter '${filterName}' not found

Error message

Entry filter '${filterName}' not found

What it means

EntryFilterProvider validates the topic-level 'entryFilterNames' policy against the set of entry filters registered with the broker. When a configured filter name does not match any known EntryFilterMetaData definition, an InvalidEntryFilterException is thrown during policy validation so the invalid namespace/topic policy is rejected early, before message processing.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/plugin/EntryFilterProvider.java:81

    }

    protected void initializeBrokerEntryFilters() throws IOException {
        if (!serviceConfiguration.getEntryFilterNames().isEmpty()) {
            brokerEntryFilters = loadEntryFilters(serviceConfiguration.getEntryFilterNames());
        } else {
            brokerEntryFilters = Collections.emptyList();
        }
    }

    public void validateEntryFilters(String entryFilterNames) throws InvalidEntryFilterException {
        if (StringUtils.isBlank(entryFilterNames)) {
            return;
        }
        final List<String> entryFilterList = readEntryFiltersString(entryFilterNames);
        for (String filterName : entryFilterList) {
            EntryFilterMetaData metaData = definitions.get(filterName);
            if (metaData == null) {
                throw new InvalidEntryFilterException("Entry filter '" + filterName + "' not found");
            }
        }
    }

    private List<String> readEntryFiltersString(String entryFilterNames) {
        final List<String> entryFilterList = Arrays.stream(entryFilterNames.split(","))
                .filter(n -> StringUtils.isNotBlank(n))
                .toList();
        return entryFilterList;
    }

    public List<EntryFilter> loadEntryFiltersForPolicy(EntryFilters policy)
            throws IOException {
        final String names = policy.getEntryFilterNames();
        if (StringUtils.isBlank(names)) {
            return Collections.emptyList();
        }
        final List<String> entryFilterList = readEntryFiltersString(names);

View on GitHub (pinned to 820761864e)

Solutions

1. Check available filter names in broker logs or the broker's entryFilter NAR directory and correct the policy value
2. Deploy the missing entry filter NAR to every broker and restart so definitions contains the name
3. Remove or rename the stale filter name from the namespace/topic policy

Example fix

// before
entryFilterNames = "AuditFilter, redact"
// after
entryFilterNames = "audit-filter"  // exact name as registered by the deployed NAR

Set<String> available = broker.getEntryFilterProvider().getDefinitions().keySet();
for (String name : policy.getEntryFilterNames().split(",")) {
    String n = name.trim();
    if (!n.isEmpty() && !available.contains(n)) {
        throw new IllegalArgumentException("Unknown entry filter: " + n + ", available: " + available);
    }
}

boolean isValidEntryFilter(String name, Map<String, EntryFilterMetaData> defs) { return defs.containsKey(name); }

try {
    provider.validateEntryFilters(policyString, definitions);
} catch (InvalidEntryFilterException e) {
    log.error("Policy references unknown entry filter: {}", e.getMessage());
}

When it happens

Trigger: Calling validateEntryFilters with a policy string containing a filter name that is not present in the broker's loaded definitions map (typo, filter NAR not deployed, filter removed after policy was set).

Common situations: Admin sets namespace/topic policy entryFilterNames=audit-filter but the audit-filter NAR was never copied to the broker's entryFilter directory; filter renamed in a newer broker version while old policies still reference the old name; comma-separated list includes whitespace/misspelled names.

Related errors

• No entry filter is found for name `${filterName}`. Available
• Broker doesn't allow forced deletion of namespaces
• Local cluster is not part of replicate cluster list
• Entry filter `${name}` does NOT provide a entry filters impl
• Entry filter `${name}` cannot be loaded, see the broker logs

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/c586d6ce48109472. Report an issue: GitHub.