alibaba/nacos · error · NacosException

INVALID_PARAM

INVALID_PARAM

Error message

instance format invalid: The weights range from 0.0 to 10000.0

What it means

Thrown by HttpRequestInstanceBuilder.setWeight() when an instance-registration HTTP request supplies a 'weight' outside [Constants.MIN_WEIGHT_VALUE, Constants.MAX_WEIGHT_VALUE] = [0.0, 10000.0]. Weight scales instance selection probability, so out-of-range values break load balancing; the builder returns NacosException.INVALID_PARAM. Note the range is inclusive bounds 0.0..10000.0.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/pojo/instance/HttpRequestInstanceBuilder.java:111

    private void setAttributesToBuilder(HttpServletRequest request) throws NacosException {
        actualBuilder.setServiceName(WebUtils.required(request, CommonParams.SERVICE_NAME));
        actualBuilder.setIp(WebUtils.required(request, "ip"));
        actualBuilder.setPort(Integer.parseInt(WebUtils.required(request, "port")));
        actualBuilder
            .setHealthy(ConvertUtils.toBoolean(WebUtils.optional(request, "healthy", "true")));
        actualBuilder.setEphemeral(ConvertUtils
            .toBoolean(
                WebUtils.optional(request, "ephemeral", String.valueOf(defaultInstanceEphemeral))));
        setWeight(request);
        setCluster(request);
        setEnabled(request);
        setMetadata(request);
    }
    
    private void setWeight(HttpServletRequest request) throws NacosException {
        double weight = Double.parseDouble(WebUtils.optional(request, "weight", "1"));
        if (weight > Constants.MAX_WEIGHT_VALUE || weight < Constants.MIN_WEIGHT_VALUE) {
            throw new NacosException(NacosException.INVALID_PARAM,
                "instance format invalid: The weights range from " + Constants.MIN_WEIGHT_VALUE
                    + " to "
                    + Constants.MAX_WEIGHT_VALUE);
        }
        actualBuilder.setWeight(weight);
    }
    
    private void setCluster(HttpServletRequest request) {
        String cluster = WebUtils.optional(request, CommonParams.CLUSTER_NAME, StringUtils.EMPTY);
        if (StringUtils.isBlank(cluster)) {
            cluster = WebUtils.optional(request, "cluster", UtilsAndCommons.DEFAULT_CLUSTER_NAME);
        }
        actualBuilder.setClusterName(cluster);
    }
    
    private void setEnabled(HttpServletRequest request) {
        String enabledString = WebUtils.optional(request, "enabled", StringUtils.EMPTY);
        boolean enabled;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set weight to a value within 0.0 .. 10000.0 (default 1).
2. If you meant a percentage, map 0-100% onto the Nacos weight scale yourself.
3. Use weight=0 to take an instance out of rotation (allowed), never a negative number.

Example fix

// before
curl -X POST '.../ns/instance' -d '...&weight=99999'
// after
curl -X POST '.../ns/instance' -d '...&weight=100'

double w = (weight == null) ? 1.0d : weight;
if (w < 0.0d || w > 10000.0d) {
    throw new IllegalArgumentException("weight must be in [0.0, 10000.0]");
}
request.addParameter("weight", String.valueOf(w));

static boolean isValidWeight(Double w) {
    return w != null && w >= 0.0d && w <= 10000.0d;
}

try {
    namingService.registerInstance(serviceName, ip, port);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM
        && e.getMessage().contains("weights range")) {
        // correct the weight and retry once
        instance.setWeight(Math.min(Math.max(instance.getWeight(), 0.0d), 10000.0d));
    } else {
        throw e;
    }
}

When it happens

Trigger: POST /v3/admin/ns/instance (or legacy /nacos/v1/ns/instance) with weight < 0 or > 10000, e.g. weight=50000 or weight=-1. The default weight is 1 when the param is omitted.

Common situations: Passing weight as a percentage (e.g. 100 meaning 100%); copy-paste error with an extra digit; weight=0 intended to drain traffic (valid - 0.0 is allowed, but negative values are not).

Related errors

• WEIGHT_ERROR
• PARAMETER_MISSING
• INVALID_PARAM
• INVALID_PARAM
• INVALID_PARAM

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