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

Use 'start-end' with a hyphen for every part, joined by ';' e.g. '0-104857600;104857600-209715200'

invalid range %q

Error message

invalid range %q

What it means

parseRanges parses a semicolon-separated 'start-end' byte range spec used for cache prefill targeting; a part lacking the '-' separator yields 'invalid range %q'. It is a spec-format validation error before any numeric parsing.

Source

Thrown at pkg/vfs/fill.go:227

	}
	logger.Infof("%s %d paths in %s", action, len(paths), time.Since(start))
}

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 {

View on GitHub (pinned to c9a67b23e8)

Solutions

Use 'start-end' with a hyphen for every part, joined by ';' e.g. '0-104857600;104857600-209715200'
Check for stray characters (commas, spaces) in the spec
Validate the spec with TestParseRangesMerge-style parsing before deploying

Example fix

// before
spec := "0-100,200-300"
// after
spec := "0-100;200-300"

Defensive patterns

Strategy: validation

Validate before calling

for _, part := range strings.Split(spec, ";") { if !strings.Contains(part, "-") { return fmt.Errorf("bad part %q", part) } }

Try / catch

ranges, err := parseRanges(spec); if err != nil { return fmt.Errorf("bad spec %q: %w", spec, err) }

Prevention

Use ';' between ranges and '-' inside each range
Test specs against the parser before production use
Never copy specs with locale-dependent separators

When it happens

Trigger: Calling SplitTarget (or the range-fill feature) with a target string where any ';'-separated part has no dash, e.g. '0-100;200300' or a stray token.

Common situations: Hand-written --sub-dir/prefill range specs; typos like comma or space instead of dash; copied specs with wrong separators.

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/bfd278df8393df26. Report an issue: GitHub.