alibaba/nacos · error · NacosApiException

INSTANCE_METADATA_ERROR

INSTANCE_METADATA_ERROR

Error message

metadata format incorrect:{metadata}

What it means

Thrown by UtilsAndCommons.parseMetadata when the metadata string is neither valid JSON (Map<String,String>) nor valid comma-separated key=value pairs. The method first tries JSON deserialization; on failure it falls back to splitting on ',' and '='. Each fallback entry must have exactly one '=' producing exactly 2 parts (kv.length == 2). This error carries ErrorCode.INSTANCE_METADATA_ERROR.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/misc/UtilsAndCommons.java:204

     */
    public static Map<String, String> parseMetadata(String metadata) throws NacosException {
        
        Map<String, String> metadataMap = new HashMap<>(16);
        
        if (StringUtils.isBlank(metadata)) {
            return metadataMap;
        }
        
        try {
            metadataMap = JacksonUtils.toObj(metadata, new TypeReference<Map<String, String>>() {
            });
        } catch (Exception e) {
            String[] datas = metadata.split(",");
            if (datas.length > 0) {
                for (String data : datas) {
                    String[] kv = data.split("=");
                    if (kv.length != 2) {
                        throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                            ErrorCode.INSTANCE_METADATA_ERROR,
                            "metadata format incorrect:" + metadata);
                    }
                    metadataMap.put(kv[0], kv[1]);
                }
            }
        }
        
        return metadataMap;
    }
    
    /**
     * Provide a number between 0(inclusive) and {@code upperLimit}(exclusive) for the given {@code string}, the number
     * will be nearly uniform distribution.
     *
     * <p>e.g. Assume there's an array which contains some IP of the servers provide the same service, the caller name
     * can be used to choose the server to achieve load balance.
     * <blockquote><pre>

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass metadata as valid JSON: {"key":"value"}.
2. Or pass as comma-separated key=value pairs: 'key1=val1,key2=val2'.
3. Ensure every entry has exactly one '=' with non-empty key and value.

Example fix

// before
POST /v3/admin/ns/instance?metadata=key
// after
POST /v3/admin/ns/instance?metadata={"version":"1.0","env":"prod"}

// Pre-validate metadata before calling the API
try {
    objectMapper.readValue(metadata, new TypeReference<Map<String,String>>(){});
} catch (Exception jsonEx) {
    for (String kv : metadata.split(",")) {
        String[] parts = kv.split("=", 2);
        if (parts.length != 2 || parts[0].isEmpty()) {
            throw new IllegalArgumentException("Bad metadata entry: " + kv);
        }
    }
}

function isValidMetadata(metadata: string): boolean {
  try {
    const obj = JSON.parse(metadata);
    return typeof obj === 'object' && obj !== null;
  } catch {
    return metadata.split(',').every(kv => {
      const parts = kv.split('=');
      return parts.length === 2 && parts[0].length > 0;
    });
  }
}

try {
  namingService.registerInstance(serviceName, ip, port, metadata);
} catch (NacosApiException e) {
  if (e.getErrCode() == 400 && e.getMessage().contains("metadata format incorrect")) {
    metadata = objectMapper.writeValueAsString(parsedMetadataMap); // re-send as JSON
  }
}

When it happens

Trigger: Any naming API that accepts a 'metadata' parameter (instance registration, metadata update) with a malformed string, e.g. metadata='key' (no '='), metadata='key=value=extra' (multiple '='), metadata='{bad json', metadata='a=b,c' (second entry has no '=').

Common situations: Passing metadata in an unsupported format, missing the '=' in some entries, or partial JSON that is neither valid JSON nor valid k=v.

Related errors

• PARAMETER_MISSING
• 10000
• 400
• WEIGHT_ERROR
• PARAMETER_VALIDATE_ERROR

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