{"record":{"id":"2d5640b748e83948","repo":"XTLS/Xray-core","slug":"invalid-address","errorCode":null,"errorMessage":"invalid address: ","messagePattern":"invalid address: ","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/common.go","lineNumber":57,"sourceCode":"\t\treturn nil\n\t}\n\treturn errors.New(\"unknown format of a string list: \" + string(data))\n}\n\ntype Address struct {\n\tnet.Address\n}\n\n// MarshalJSON implements encoding/json.Marshaler.MarshalJSON\nfunc (v *Address) MarshalJSON() ([]byte, error) {\n\treturn json.Marshal(v.Address.String())\n}\n\n// UnmarshalJSON implements encoding/json.Unmarshaler.UnmarshalJSON\nfunc (v *Address) UnmarshalJSON(data []byte) error {\n\tvar rawStr string\n\tif err := json.Unmarshal(data, &rawStr); err != nil {\n\t\treturn errors.New(\"invalid address: \", string(data)).Base(err)\n\t}\n\tif strings.HasPrefix(rawStr, \"env:\") {\n\t\trawStr = platform.NewEnvFlag(rawStr[4:]).GetValue(func() string { return \"\" })\n\t}\n\tv.Address = net.ParseAddress(rawStr)\n\n\treturn nil\n}\n\nfunc (v *Address) Build() *net.IPOrDomain {\n\treturn net.NewIPOrDomain(v.Address)\n}\n\ntype Network string\n\nfunc (v Network) Build() net.Network {\n\tswitch strings.ToLower(string(v)) {\n\tcase \"tcp\":","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/common.go#L39-L75","documentation":"Thrown by Address.UnmarshalJSON in infra/conf/common.go when the JSON value for an address field cannot be unmarshaled into a plain JSON string. The value must be a JSON string (it may carry an env: prefix which is resolved via platform.NewEnvFlag). If it is a number, object, array, or malformed JSON, this error wraps the underlying json error.","triggerScenarios":"Any field typed conf.Address (server 'address', DNS nameserver address, stream security SNI-ish fields) given a non-string: \"address\": 8.8.8.8 (unquoted IP becomes a number or two numbers), \"address\": [\"a\",\"b\"], or \"address\": {\"host\":\"x\"}.","commonSituations":"Forgetting quotes around a numeric IP so JSON parses it as a number (8.8.8.8 unquoted is actually invalid JSON with two dots, but 1.2 becomes a number); pasting an object form where only a string is accepted; env: variable names that expand to an empty string are accepted here but fail later at net.ParseAddress.","solutions":["Quote the address value: \"address\": \"8.8.8.8\" instead of 8.8.8.8","If you need a domain + port, keep only the host in the address field; ports go in their own 'port' field","For env substitution use the string form \"env:MY_HOST\" and ensure the variable is exported","Inspect the wrapped json error (the .Base(err) chain) to see the exact JSON syntax problem"],"exampleFix":"// before\n\"address\": 1.2.3.4\n\n// after\n\"address\": \"1.2.3.4\"","handlingStrategy":"validation","validationCode":"func isValidAddressJSON(raw []byte) bool {\n    var s string\n    return json.Unmarshal(raw, &s) == nil // Address accepts any string; net.ParseAddress decides later\n}","typeGuard":null,"tryCatchPattern":"if err := json.Unmarshal(data, &addr); err != nil {\n    if strings.Contains(err.Error(), \"invalid address\") {\n        return fmt.Errorf(\"address field must be a JSON string, got: %s\", data)\n    }\n    return err\n}","preventionTips":["Always quote address values including bare IPs","Keep host in 'address' and port in 'port'","Test env: variables resolve to non-empty strings before launch"],"tags":["config","json","address","validation","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}