{"record":{"id":"36b4fe540905a22b","repo":"alibaba/nacos","slug":"instance-metadata-error","errorCode":"INSTANCE_METADATA_ERROR","errorMessage":"metadata format incorrect:{metadata}","messagePattern":"metadata format incorrect:(.+?)","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"naming/src/main/java/com/alibaba/nacos/naming/misc/UtilsAndCommons.java","lineNumber":204,"sourceCode":"     */\n    public static Map<String, String> parseMetadata(String metadata) throws NacosException {\n        \n        Map<String, String> metadataMap = new HashMap<>(16);\n        \n        if (StringUtils.isBlank(metadata)) {\n            return metadataMap;\n        }\n        \n        try {\n            metadataMap = JacksonUtils.toObj(metadata, new TypeReference<Map<String, String>>() {\n            });\n        } catch (Exception e) {\n            String[] datas = metadata.split(\",\");\n            if (datas.length > 0) {\n                for (String data : datas) {\n                    String[] kv = data.split(\"=\");\n                    if (kv.length != 2) {\n                        throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),\n                            ErrorCode.INSTANCE_METADATA_ERROR,\n                            \"metadata format incorrect:\" + metadata);\n                    }\n                    metadataMap.put(kv[0], kv[1]);\n                }\n            }\n        }\n        \n        return metadataMap;\n    }\n    \n    /**\n     * Provide a number between 0(inclusive) and {@code upperLimit}(exclusive) for the given {@code string}, the number\n     * will be nearly uniform distribution.\n     *\n     * <p>e.g. Assume there's an array which contains some IP of the servers provide the same service, the caller name\n     * can be used to choose the server to achieve load balance.\n     * <blockquote><pre>","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/misc/UtilsAndCommons.java#L186-L222","documentation":"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.","triggerScenarios":"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 '=').","commonSituations":"Passing metadata in an unsupported format, missing the '=' in some entries, or partial JSON that is neither valid JSON nor valid k=v.","solutions":["Pass metadata as valid JSON: {\"key\":\"value\"}.","Or pass as comma-separated key=value pairs: 'key1=val1,key2=val2'.","Ensure every entry has exactly one '=' with non-empty key and value."],"exampleFix":"// before\nPOST /v3/admin/ns/instance?metadata=key\n// after\nPOST /v3/admin/ns/instance?metadata={\"version\":\"1.0\",\"env\":\"prod\"}","handlingStrategy":"validation","validationCode":"// Pre-validate metadata before calling the API\ntry {\n    objectMapper.readValue(metadata, new TypeReference<Map<String,String>>(){});\n} catch (Exception jsonEx) {\n    for (String kv : metadata.split(\",\")) {\n        String[] parts = kv.split(\"=\", 2);\n        if (parts.length != 2 || parts[0].isEmpty()) {\n            throw new IllegalArgumentException(\"Bad metadata entry: \" + kv);\n        }\n    }\n}","typeGuard":"function isValidMetadata(metadata: string): boolean {\n  try {\n    const obj = JSON.parse(metadata);\n    return typeof obj === 'object' && obj !== null;\n  } catch {\n    return metadata.split(',').every(kv => {\n      const parts = kv.split('=');\n      return parts.length === 2 && parts[0].length > 0;\n    });\n  }\n}","tryCatchPattern":"try {\n  namingService.registerInstance(serviceName, ip, port, metadata);\n} catch (NacosApiException e) {\n  if (e.getErrCode() == 400 && e.getMessage().contains(\"metadata format incorrect\")) {\n    metadata = objectMapper.writeValueAsString(parsedMetadataMap); // re-send as JSON\n  }\n}","preventionTips":["Always send metadata as a JSON object string for maximum compatibility.","If using k=v format, ensure every entry has exactly one '='."],"tags":["naming","metadata","validation","instance"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}