alibaba/nacos · error · IllegalArgumentException

The parameter 'metadata' cannot be null.

Error message

The parameter 'metadata' cannot be null.

What it means

Thrown by NamingSelectorFactory.newMetadataSelector when the metadata map is null (IllegalArgumentException). The selector factory iterates the metadata entries to build a predicate chain; a null map would cause a NullPointerException in the loop.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/naming/selector/NamingSelectorFactory.java:127

     * Create a metadata selector.
     *
     * @param metadata metadata that needs to be matched
     * @return metadata selector
     */
    public static NamingSelector newMetadataSelector(Map<String, String> metadata) {
        return newMetadataSelector(metadata, false);
    }
    
    /**
     * Create a metadata selector.
     *
     * @param metadata target metadata
     * @param isAny    true if any of the metadata needs to be matched, false if all the metadata need to be matched.
     * @return metadata selector
     */
    public static NamingSelector newMetadataSelector(Map<String, String> metadata, boolean isAny) {
        if (metadata == null) {
            throw new IllegalArgumentException("The parameter 'metadata' cannot be null.");
        }
        
        Predicate<Instance> filter = instance -> instance.getMetadata().size() >= metadata.size();
        
        for (Map.Entry<String, String> entry : metadata.entrySet()) {
            Predicate<Instance> nextFilter = instance -> {
                Map<String, String> map = instance.getMetadata();
                return Objects.equals(map.get(entry.getKey()), entry.getValue());
            };
            if (isAny) {
                filter = filter.or(nextFilter);
            } else {
                filter = filter.and(nextFilter);
            }
        }
        return new DefaultNamingSelector(filter);
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass a non-null Map (use Collections.emptyMap() if no metadata filtering is needed).
2. Null-check the metadata variable and skip selector creation or use a default empty map.
3. Review the data source for the metadata map to ensure it is initialized.

Example fix

// before
NamingSelector selector = NamingSelectorFactory.newMetadataSelector(meta);

// after
Map<String, String> meta = optionalMeta != null ? optionalMeta : Collections.emptyMap();
NamingSelector selector = NamingSelectorFactory.newMetadataSelector(meta);

Map<String, String> safeMeta = (metadata != null) ? metadata : Collections.emptyMap();
NamingSelector selector = NamingSelectorFactory.newMetadataSelector(safeMeta, isAny);

When it happens

Trigger: Calling NamingSelectorFactory.newMetadataSelector(null) or newMetadataSelector(null, isAny). The null check guards the entry-set iteration.

Common situations: Passing a nullable metadata map from a config or request object without null-checking; building a selector from optional metadata that may be absent.

Related errors

• The parameter 'regex' cannot be null.
• 400
• 400
• SELECTOR_ERROR
• 400

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/215cf7f19953e28e. Report an issue: GitHub.