What causes "bucket name required" in juicedata/juicefs?

Append the bucket name to the URL path: use dragonfly:// / instead of dragonfly:// .

bucket name required

Error message

bucket name required

What it means

newDragonfly parses the dragonfly:// endpoint URL and takes the URL path as the bucket name. If the URL has no path component (e.g. dragonfly://host:8000), there is no bucket to operate on, so construction fails immediately with this error. The Dragonfly client requires every operation to be scoped to a bucket under /buckets/<bucket>/.

Source

Thrown at pkg/object/dragonfly.go:536

	return generateListResult(objs, limit)
}

// newDragonfly creates a new dragonfly object storage.
func newDragonfly(endpoint, accessKey, secretKey, token string) (ObjectStorage, error) {
	if !strings.Contains(endpoint, "://") {
		endpoint = fmt.Sprintf("http://%s", endpoint)
	}

	// Parse the endpoint.
	uri, err := url.Parse(endpoint)
	if err != nil {
		return nil, err
	}

	endpoint = uri.Scheme + "://" + uri.Host
	bucket := uri.Path
	if bucket == "" {
		return nil, fmt.Errorf("bucket name required")
	}

	if !strings.Contains(endpoint, "://") {
		endpoint = fmt.Sprintf("http://%s", endpoint)
	}

	mode := WriteBack
	if value := uri.Query().Get("mode"); value != "" {
		mode, err = strconv.Atoi(value)
		if err != nil || (mode != WriteBack && mode != AsyncWriteBack) {
			return nil, fmt.Errorf("unexpected dragonfly mode: %s", value)
		}
	}

	maxReplicas := DefaultMaxReplicas
	if value := uri.Query().Get("maxReplicas"); value != "" {
		maxReplicas, err = strconv.Atoi(value)
		if err != nil || maxReplicas > MaxReplicasLimit || maxReplicas < 0 {

View on GitHub (pinned to c9a67b23e8)

Solutions

Append the bucket name to the URL path: use dragonfly://<host>/<bucket> instead of dragonfly://<host>.
If the endpoint comes from config or an env var, check it contains a non-empty path before passing it to the client.
For other schemes (e.g. s3://, oss://), ensure you are using the dragonfly scheme correctly — the bucket is the first path segment, not a query parameter.

Example fix

// before
endpoint := "dragonfly://dfdaemon.example.com:8000"
// after
endpoint := "dragonfly://dfdaemon.example.com:8000/mybucket"

Defensive patterns

Strategy: validation

Validate before calling

u, _ := url.Parse(endpoint)
if u.Scheme == "dragonfly" && strings.Trim(u.Path, "/") == "" {
    return errors.New("dragonfly URL requires a bucket: dragonfly://host/bucket")
}

Prevention

Always include the bucket as the first path segment: dragonfly://host:8000/bucket.
Validate the endpoint in config loading before passing it to juicefs format/mount.
When generating URLs from host-only values, append the bucket explicitly.
Add a startup smoke test that constructs the client so config errors surface early.

When it happens

Trigger: Constructing a dragonfly object storage via newDragonfly (registered as "dragonfly" scheme, e.g. during juicefs format/mount) with a URL lacking a path: "dragonfly://host:8000", "http://host:8000", or a URL with an empty path after parsing.

Common situations: Copy-pasting a dfdaemon address without appending the bucket name; environment-variable-driven endpoint configs where the bucket part is dropped; automation generating URLs from host-only values; confusion with other object storage clients where the bucket is passed separately.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/d4f3083ac3d2f860. Report an issue: GitHub.