alibaba/nacos · error · NacosApiException

400

400

Error message

Parameter `newMetadata` can't be null

What it means

Thrown by NacosNameMaintainerServiceImpl.batchUpdateInstanceMetadata when the newMetadata argument is null. It is a client-side validation guard (NacosApiException, INVALID_PARAM=400, ErrorCode.PARAMETER_MISSING=10000) raised before any HTTP request is sent. The maintainer client refuses to build the batch-update request because there is no metadata to apply.

Source

Thrown at maintainer-client/src/main/java/com/alibaba/nacos/maintainer/client/naming/NacosNamingMaintainerServiceImpl.java:335

        RequestResource resource = buildRequestResource(service);
        HttpRequest httpRequest = buildRequestWithResource(resource).setHttpMethod(HttpMethod.PUT)
            .setPath(appendQuery(Constants.AdminApiPath.NAMING_INSTANCE_ADMIN_PATH, params))
            .build();
        HttpRestResult<String> httpRestResult =
            getClientHttpProxy().executeSyncHttpRequest(httpRequest);
        Result<String> result =
            JsonUtils.toObj(httpRestResult.getData(), new NacosTypeReference<Result<String>>() {
            });
        return result.getData();
    }
    
    @Override
    public InstanceMetadataBatchResult batchUpdateInstanceMetadata(Service service,
        List<Instance> instances,
        Map<String, String> newMetadata) throws NacosException {
        service.validate();
        if (Objects.isNull(newMetadata)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Parameter `newMetadata` can't be null");
        }
        if (instances.isEmpty()) {
            return new InstanceMetadataBatchResult(Collections.emptyList());
        }
        for (Instance each : instances) {
            each.validate();
        }
        checkEphemeral(service, instances.get(0));
        Map<String, String> params = RequestUtil.toParameters(service, instances, newMetadata);
        RequestResource resource = buildRequestResource(service);
        HttpRequest httpRequest = buildRequestWithResource(resource).setHttpMethod(HttpMethod.PUT)
            .setPath(
                appendQuery(Constants.AdminApiPath.NAMING_INSTANCE_ADMIN_PATH + "/metadata/batch",
                    params))
            .build();
        HttpRestResult<String> httpRestResult =
            getClientHttpProxy().executeSyncHttpRequest(httpRequest);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass a non-null Map (use Collections.emptyMap() when no metadata changes are needed) before calling batchUpdateInstanceMetadata.
2. Add a null-check in the calling code and short-circuit with a no-op or log warning when the metadata map is null.
3. If the metadata source can legitimately be null, default it: newMetadata = new HashMap<>() before the call.

Example fix

// before
maintainerService.batchUpdateInstanceMetadata(service, instances, null);

// after
Map<String,String> metadata = newMetadata == null ? Collections.emptyMap() : newMetadata;
if (!metadata.isEmpty()) {
    maintainerService.batchUpdateInstanceMetadata(service, instances, metadata);
}

if (newMetadata == null) {
    throw new IllegalArgumentException("newMetadata must not be null");
}
// or short-circuit:
Map<String, String> safeMetadata = newMetadata != null ? newMetadata : Collections.emptyMap();
maintainerService.batchUpdateInstanceMetadata(service, instances, safeMetadata);

When it happens

Trigger: Calling NamingMaintainerService.batchUpdateInstanceMetadata(Service, List<Instance>, Map<String,String> newMetadata) with newMetadata explicitly set to null. The check runs right after service.validate() and before the instances list is iterated.

Common situations: Caller computes the new metadata map from upstream config or user input that happened to be empty/uninitialized, leaving the reference null. Refactor that introduced a new call path forgetting to pass the map. Deserialization from a request body where the metadata JSON field was absent.

Related errors

• 400
• The parameter 'regex' cannot be null.
• The parameter 'metadata' cannot be null.
• 400
• INSTANCE_METADATA_ERROR

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