alibaba/nacos · error · NacosApiException

400

400

Error message

Instance can not be null.

What it means

checkInstanceIsLegal null-checks the Instance argument first (NacosApiException, 400, ErrorCode.INSTANCE_ERROR). Any later field access would NPE, so the method fails fast with a clear message.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/naming/utils/NamingUtils.java:175

     */
    public static String getGroupedNameOptional(final String serviceName, final String groupName) {
        return groupName + Constants.SERVICE_INFO_SPLITER + serviceName;
    }
    
    /**
     * <p>Check instance param about keep alive.</p>
     *
     * <pre>
     * heart beat timeout must > heart beat interval
     * ip delete timeout must  > heart beat interval
     * </pre>
     *
     * @param instance need checked instance
     * @throws NacosException if check failed, throw exception
     */
    public static void checkInstanceIsLegal(Instance instance) throws NacosException {
        if (null == instance) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.INSTANCE_ERROR,
                "Instance can not be null.");
        }
        instance.validate();
        if (instance.getInstanceHeartBeatTimeOut() < instance.getInstanceHeartBeatInterval()
            || instance.getIpDeleteTimeout() < instance.getInstanceHeartBeatInterval()) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.INSTANCE_ERROR,
                "Instance 'heart beat interval' must less than 'heart beat timeout' and 'ip delete timeout'.");
        }
        if (!StringUtils.isEmpty(instance.getClusterName())
            && !CLUSTER_NAME_PATTERN.matcher(instance.getClusterName())
                .matches()) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.INSTANCE_ERROR,
                String.format(
                    "Instance 'clusterName' should be characters with only 0-9a-zA-Z-. (current: %s)",
                    instance.getClusterName()));
        }
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass a populated Instance.
2. Filter nulls out of batch lists before calling batchRegisterInstance.
3. Return a sentinel/error from mappers instead of null.

Example fix

// before
NamingUtils.checkInstanceIsLegal(maybeNullInstance);  // throws 546

// after
if (instance == null) throw new IllegalArgumentException("instance required");
NamingUtils.checkInstanceIsLegal(instance);

if (instance == null) {
    throw new IllegalArgumentException("instance must not be null");
}

boolean isRegisterable(Instance i) {
    return i != null && i.getIp() != null && i.getPort() > 0;
}

When it happens

Trigger: registerInstance(null); batch register whose list contains a null element; deserialization that produced a null Instance.

Common situations: Loop registering a list where one element failed to construct; mapping code returning null on parse error and forwarding it.

Related errors

• 10000
• The parameter 'regex' cannot be null.
• The parameter 'metadata' cannot be null.
• WEIGHT_ERROR
• PARAMETER_VALIDATE_ERROR

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