What causes "invalid range %q: %w" in juicedata/juicefs?

Ensure start is a plain non-negative decimal integer fitting in uint64

invalid range %q: %w

Error message

invalid range %q: %w

What it means

Returned by parseRanges (used by parallel fill --ranges) when a range token lacks the '-' separator or its start/end values are not valid unsigned integers. Each range must look like 'start-end', e.g. '0-1048575'.

Source

Thrown at pkg/vfs/fill.go:231

func sendFile(ctx meta.Context, todo chan _file, f _file) error {
	select {
	case todo <- f:
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

func parseRanges(spec string) ([]ByteRange, error) {
	var ranges []ByteRange
	for _, part := range strings.Split(spec, ";") {
		sep := strings.IndexByte(part, '-')
		if sep < 0 {
			return nil, fmt.Errorf("invalid range %q", part)
		}
		start, err := strconv.ParseUint(part[:sep], 10, 64)
		if err != nil {
			return nil, fmt.Errorf("invalid range %q: %w", part, err)
		}
		end, err := strconv.ParseUint(part[sep+1:], 10, 64)
		if err != nil {
			return nil, fmt.Errorf("invalid range %q: %w", part, err)
		}
		if end <= start {
			return nil, fmt.Errorf("invalid range %q: end must be greater than start", part)
		}
		ranges = append(ranges, ByteRange{Start: start, End: end})
	}
	sort.Slice(ranges, func(i, j int) bool { return ranges[i].Start < ranges[j].Start })
	merged := ranges[:0]
	for _, r := range ranges {
		if n := len(merged); n > 0 && r.Start <= merged[n-1].End {
			if r.End > merged[n-1].End {
				merged[n-1].End = r.End
			}
			continue

View on GitHub (pinned to c9a67b23e8)

Solutions

Ensure start is a plain non-negative decimal integer fitting in uint64
Remove sign or non-digit characters
Keep byte offsets within uint64 range

Example fix

// before
"x-100"
// after
"0-100"

Defensive patterns

Strategy: validation

Validate before calling

if _, err := strconv.ParseUint(strings.SplitN(part, "-", 2)[0], 10, 64); err != nil { return err }

Try / catch

if _, err := parseRanges(spec); err != nil { log.Fatalf("invalid fill spec: %v", err) }

Prevention

Use plain decimal integers only
Keep offsets within uint64 range
Reject negative or signed numbers at config load

When it happens

Trigger: A range part like 'abc-100', '-5-10' or a value above uint64 range passed into the fill/target spec.

Common situations: Negative numbers in the spec; non-numeric characters; gigantic numbers exceeding 64-bit.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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