{"record":{"id":"f27d265b618d0c94","repo":"juicedata/juicefs","slug":"unexpected-dragonfly-mode-s","errorCode":null,"errorMessage":"unexpected dragonfly mode: %s","messagePattern":"unexpected dragonfly mode: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/object/dragonfly.go","lineNumber":547,"sourceCode":"\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tendpoint = uri.Scheme + \"://\" + uri.Host\n\tbucket := uri.Path\n\tif bucket == \"\" {\n\t\treturn nil, fmt.Errorf(\"bucket name required\")\n\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 {","sourceCodeStart":529,"sourceCodeEnd":565,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/object/dragonfly.go#L529-L565","documentation":"newDragonfly reads the optional \"mode\" query parameter of the dragonfly:// URL, which must parse as an integer equal to WriteBack (0) or AsyncWriteBack (1). Any other value — non-numeric or out of the accepted set — fails construction with this error. The mode controls how uploaded objects are written back to the backing object storage.","triggerScenarios":"Using a URL like dragonfly://host/bucket?mode=2, ?mode=writeback (string instead of number), ?mode=-1, or any mode value not exactly 0 or 1 when creating a dragonfly object storage (via TestDragonfly or format/mount).","commonSituations":"Passing descriptive mode names (\"writeback\", \"async\") instead of the numeric values 0/1; guessing mode values beyond the two supported ones; config templating inserting an empty or malformed value that slips past the != \"\" check (e.g. whitespace); copying a URL from newer Dragonfly docs that mention additional modes.","solutions":["Use the numeric values: mode=0 (WriteBack) or mode=1 (AsyncWriteBack); remove the parameter entirely to accept the default (AsyncWriteBack is used as the internal default here).","Trim whitespace and validate the parameter is an integer 0 or 1 before building the URL.","Check the Dragonfly version's supported modes; only 0 and 1 are accepted by this client."],"exampleFix":"// before\nurl := \"dragonfly://host/bucket?mode=writeback\"\n// after\nurl := \"dragonfly://host/bucket?mode=1\"","handlingStrategy":"validation","validationCode":"if m := u.Query().Get(\"mode\"); m != \"\" && m != \"0\" && m != \"1\" {\n    return fmt.Errorf(\"mode must be 0 (WriteBack) or 1 (AsyncWriteBack), got %q\", m)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use only numeric mode values 0 or 1 in the URL; never names like \"writeback\".","Omit the mode parameter to accept the default instead of guessing values.","Trim whitespace from templated config values before URL assembly.","Document accepted modes where the mount URL is generated."],"tags":["configuration","url","dragonfly","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}