{"record":{"id":"47478ed766a4ba4a","repo":"XTLS/Xray-core","slug":"unknown-format-of-a-string-list","errorCode":null,"errorMessage":"unknown format of a string list: ","messagePattern":"unknown format of a string list: ","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/common.go","lineNumber":41,"sourceCode":"func (v StringList) Len() int {\n\treturn len(v)\n}\n\n// UnmarshalJSON implements encoding/json.Unmarshaler.UnmarshalJSON\nfunc (v *StringList) UnmarshalJSON(data []byte) error {\n\tvar strarray []string\n\tif err := json.Unmarshal(data, &strarray); err == nil {\n\t\t*v = *NewStringList(strarray)\n\t\treturn nil\n\t}\n\n\tvar rawstr string\n\tif err := json.Unmarshal(data, &rawstr); err == nil {\n\t\tstrlist := strings.Split(rawstr, \",\")\n\t\t*v = *NewStringList(strlist)\n\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:\") {","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/common.go#L23-L59","documentation":"Thrown by StringList.UnmarshalJSON in infra/conf/common.go when a JSON value expected to be a string list can be parsed neither as a JSON array of strings nor as a single comma-separated string. Xray first tries json.Unmarshal into []string, then into a raw string split on ','. If both fail (the value is a number, boolean, object, or null), this error is returned. The offending raw JSON data is appended to the message.","triggerScenarios":"Any config field typed conf.StringList (e.g. inbound/outbound 'tag' arrays, 'allocStrategy' fallbacks, 'certificates' arrays in some versions, routing 'network' is separate) receiving a non-string JSON type. Examples: \"inboundTag\": 123, \"domain\": {\"type\":\"x\"}, or \"address\": [1,2] where array elements are not strings.","commonSituations":"YAML-to-JSON config conversion mistakes where a scalar stays unquoted and becomes a number or boolean; passing an object where a list of domain strings is expected; trailing commas or malformed JSON that makes the array unmarshal fail while the string fallback also fails.","solutions":["Change the JSON value to an array of strings, e.g. \"inboundTag\": [\"tag1\",\"tag2\"]","Or supply a single comma-separated string, e.g. \"inboundTag\": \"tag1,tag2\"","Check the error suffix (the raw JSON data) to identify exactly which field produced it","Validate the whole config with `xray run -test -c config.json` or an JSON schema linter before deployment"],"exampleFix":"// before\n\"inboundTag\": 123\n\n// after\n\"inboundTag\": [\"123\"]","handlingStrategy":"validation","validationCode":"// before unmarshaling, assert the JSON value is a string or array of strings\nfunc isStringListJSON(raw []byte) bool {\n    var arr []string\n    if json.Unmarshal(raw, &arr) == nil {\n        return true\n    }\n    var s string\n    return json.Unmarshal(raw, &s) == nil\n}","typeGuard":null,"tryCatchPattern":"if err := json.Unmarshal(data, &stringList); err != nil {\n    if strings.Contains(err.Error(), \"unknown format of a string list\") {\n        // log the raw field value and point the user at the array/comma-string forms\n    }\n    return fmt.Errorf(\"config field %q: %w\", fieldName, err)\n}","preventionTips":["Always quote string-list entries in JSON configs","Run `xray run -test -c config.json` after every config edit","Generate configs from typed structs instead of hand-written JSON where possible"],"tags":["config","json","validation","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}