{"record":{"id":"94fe8af079304706","repo":"juicedata/juicefs","slug":"unexpected-dragonfly-max-replicas-s","errorCode":null,"errorMessage":"unexpected dragonfly max replicas: %s","messagePattern":"unexpected dragonfly max replicas: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/object/dragonfly.go","lineNumber":555,"sourceCode":"\t}\n\n\tif !strings.Contains(endpoint, \"://\") {\n\t\tendpoint = fmt.Sprintf(\"http://%s\", endpoint)\n\t}\n\n\tmode := WriteBack\n\tif value := uri.Query().Get(\"mode\"); value != \"\" {\n\t\tmode, err = strconv.Atoi(value)\n\t\tif err != nil || (mode != WriteBack && mode != AsyncWriteBack) {\n\t\t\treturn nil, fmt.Errorf(\"unexpected dragonfly mode: %s\", value)\n\t\t}\n\t}\n\n\tmaxReplicas := DefaultMaxReplicas\n\tif value := uri.Query().Get(\"maxReplicas\"); value != \"\" {\n\t\tmaxReplicas, err = strconv.Atoi(value)\n\t\tif err != nil || maxReplicas > MaxReplicasLimit || maxReplicas < 0 {\n\t\t\treturn nil, fmt.Errorf(\"unexpected dragonfly max replicas: %s\", value)\n\t\t}\n\t}\n\n\tmetadata, err := getObjectStorageMetadata(endpoint)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar filter string\n\tswitch metadata.Name {\n\tcase \"s3\":\n\t\tfilter = FilterS3\n\tcase \"oss\":\n\t\tfilter = FilterOSS\n\tcase \"obs\":\n\t\tfilter = FilterOBS\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unexpected dragonfly object storage name: %s\", metadata.Name)","sourceCodeStart":537,"sourceCodeEnd":573,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/object/dragonfly.go#L537-L573","documentation":"newDragonfly reads the optional \"maxReplicas\" query parameter of the dragonfly:// URL, which must parse as an integer between 0 and MaxReplicasLimit inclusive. Values that are non-numeric, negative, or above the limit fail construction with this error. maxReplicas controls how many replicas Dragonfly keeps of each uploaded object across peers.","triggerScenarios":"Using a URL like dragonfly://host/bucket?maxReplicas=abc, ?maxReplicas=-1, or ?maxReplicas=<value above MaxReplicasLimit> when creating a dragonfly object storage (via TestDragonfly or format/mount).","commonSituations":"Typo or non-numeric value in the mount URL; tuning replicas to a value exceeding the Dragonfly cluster's MaxReplicasLimit; negative values from misconfigured templates; copy-pasting a replicas setting intended for a different system.","solutions":["Set maxReplicas to an integer between 0 and MaxReplicasLimit, or omit the parameter to use DefaultMaxReplicas.","Check MaxReplicasLimit in pkg/object/dragonfly.go and clamp your configured value to it.","Validate the parameter parses as a non-negative integer before building the URL."],"exampleFix":"// before\nurl := \"dragonfly://host/bucket?maxReplicas=100\"\n// after (within limit)\nurl := \"dragonfly://host/bucket?maxReplicas=3\"","handlingStrategy":"validation","validationCode":"if v := u.Query().Get(\"maxReplicas\"); v != \"\" {\n    n, err := strconv.Atoi(v)\n    if err != nil || n < 0 || n > MaxReplicasLimit {\n        return fmt.Errorf(\"maxReplicas must be 0..%d, got %q\", MaxReplicasLimit, v)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp configured maxReplicas to 0..MaxReplicasLimit before building the URL.","Omit the parameter to use DefaultMaxReplicas when unsure.","Validate numeric query parameters centrally in config parsing.","Keep replica settings consistent with the Dragonfly cluster's limits."],"tags":["configuration","url","dragonfly","validation"],"backgroundTag":"value-out-of-range","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}