juicedata/juicefs · error

unexpected dragonfly mode: %s

Error message

unexpected dragonfly mode: %s

What it means

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.

Source

Thrown at pkg/object/dragonfly.go:547

	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 {
			return nil, fmt.Errorf("unexpected dragonfly max replicas: %s", value)
		}
	}

	metadata, err := getObjectStorageMetadata(endpoint)
	if err != nil {
		return nil, err
	}

	var filter string
	switch metadata.Name {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. 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).
2. Trim whitespace and validate the parameter is an integer 0 or 1 before building the URL.
3. Check the Dragonfly version's supported modes; only 0 and 1 are accepted by this client.

Example fix

// before
url := "dragonfly://host/bucket?mode=writeback"
// after
url := "dragonfly://host/bucket?mode=1"

if m := u.Query().Get("mode"); m != "" && m != "0" && m != "1" {
    return fmt.Errorf("mode must be 0 (WriteBack) or 1 (AsyncWriteBack), got %q", m)
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unexpected dragonfly max replicas: %s
• bucket name required
• illegal value for parameter 'ranger-rest-url': " + url
• illegal value for parameter 'ranger-service': " + serviceNam
• invalid endpoint: %s

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