What causes "unexpected dragonfly max replicas: %s" in juicedata/juicefs?

Set maxReplicas to an integer between 0 and MaxReplicasLimit, or omit the parameter to use DefaultMaxReplicas.

unexpected dragonfly max replicas: %s

Error message

unexpected dragonfly max replicas: %s

What it means

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.

Source

Thrown at pkg/object/dragonfly.go:555

	}

	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 {
	case "s3":
		filter = FilterS3
	case "oss":
		filter = FilterOSS
	case "obs":
		filter = FilterOBS
	default:
		return nil, fmt.Errorf("unexpected dragonfly object storage name: %s", metadata.Name)

View on GitHub (pinned to c9a67b23e8)

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.

Example fix

// before
url := "dragonfly://host/bucket?maxReplicas=100"
// after (within limit)
url := "dragonfly://host/bucket?maxReplicas=3"

Defensive patterns

Strategy: validation

Validate before calling

if v := u.Query().Get("maxReplicas"); v != "" {
    n, err := strconv.Atoi(v)
    if err != nil || n < 0 || n > MaxReplicasLimit {
        return fmt.Errorf("maxReplicas must be 0..%d, got %q", MaxReplicasLimit, v)
    }
}

Prevention

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.

When it happens

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

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

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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