{"record":{"id":"5647851a99bed488","repo":"juicedata/juicefs","slug":"unexpected-dragonfly-object-storage-name-s","errorCode":null,"errorMessage":"unexpected dragonfly object storage name: %s","messagePattern":"unexpected dragonfly object storage name: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/object/dragonfly.go","lineNumber":573,"sourceCode":"\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)\n\t}\n\n\treturn &dragonfly{\n\t\tendpoint:    endpoint,\n\t\tfilter:      filter,\n\t\tmode:        mode,\n\t\tmaxReplicas: maxReplicas,\n\t\tbucket:      bucket,\n\t\tclient:      httpClient,\n\t}, nil\n}\n\n// getObjectStorageMetadata returns the object storage metadata.\nfunc getObjectStorageMetadata(endpoint string) (*ObjectStorageMetadata, error) {\n\tu, err := url.Parse(endpoint)\n\tif err != nil {\n\t\treturn nil, nil\n\t}","sourceCodeStart":555,"sourceCodeEnd":591,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/object/dragonfly.go#L555-L591","documentation":"During construction, newDragonfly fetches /metadata from the Dragonfly daemon to learn which object storage backs it. The metadata Name must be one of \"s3\", \"oss\", or \"obs\"; anything else (including an empty name if the daemon returns an unexpected payload) fails construction with this error. The name determines which filter is applied when talking to the backing store.","triggerScenarios":"Pointing the dragonfly:// URL at a daemon whose GET /metadata returns a Name outside {s3, oss, obs} — e.g. a different or newer Dragonfly build reporting another backend, a non-Dragonfly HTTP service that happens to answer on that port, or a daemon misconfigured to emulate an unsupported storage.","commonSituations":"Using an incompatible Dragonfly version whose metadata endpoint reports a different storage name; proxying to a backend like Azure Blob/GCS that this client doesn't recognize; hitting the wrong port where another service responds with different JSON; older dfdaemon returning an empty name field.","solutions":["Verify the daemon's backend: curl http://<endpoint>/metadata and confirm \"name\" is s3, oss, or obs.","Upgrade/downgrade Dragonfly to a version that reports a supported backing store, or reconfigure the dfdaemon to use S3/OSS/OBS-compatible storage.","Ensure the URL points at the actual dfdaemon (default port 8000) and not another service; check for typos in host/port.","If you need a different backend, use the corresponding JuiceFS object storage scheme directly (s3://, oss://, etc.) instead of dragonfly://."],"exampleFix":"// before: pointing at an unsupported backend\nendpoint := \"dragonfly://proxy.example.com:8000/mybucket\"\n// metadata returns {\"name\":\"azureblob\"} -> error\n// after: use the backend's native scheme\nendpoint := \"azureblob://container@example.blob.core.windows.net\"","handlingStrategy":"validation","validationCode":"resp, err := http.Get(endpoint + \"/metadata\")\nif err != nil {\n    return err\n}\nvar md struct{ Name string `json:\"name\"` }\njson.NewDecoder(resp.Body).Decode(&md)\nif md.Name != \"s3\" && md.Name != \"oss\" && md.Name != \"obs\" {\n    return fmt.Errorf(\"unsupported backing store %q; use s3/oss/obs\", md.Name)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Probe GET /metadata during deployment and assert the reported name is s3/oss/obs.","Pin the Dragonfly version so the metadata endpoint stays compatible.","Point the URL at the real dfdaemon port (8000), not another Dragonfly component.","For non-S3/OSS/OBS backends, use the backend's native object storage scheme instead of dragonfly://."],"tags":["dragonfly","object-storage","compatibility","metadata"],"backgroundTag":"unsupported-config-value","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"}