What causes "get start %v: %s" in juicedata/juicefs?

Inspect the wrapped error: for timeouts, check etcd disk latency (`etcdctl endpoint health -w table`) and tune backend

get start %v: %s

Error message

get start %v: %s

What it means

The etcd `scanAll`-style background scan pages through keys with a ranged Get limited to 1024 entries at a consistent revision (`WithMaxModRev`, `WithSerializable`). If a page fetch fails it returns (not panics) an error 'get start %v: %s' naming the start key.

Source

Thrown at pkg/meta/tkv_etcd.go:270

func (c *etcdClient) scan(prefix []byte, handler func(key []byte, value []byte) bool) error {
	var start = prefix
	var end = string(nextKey(prefix))
	resp, err := c.client.Get(context.Background(), "anything")
	if err != nil {
		return err
	}
	currentRev := resp.Header.Revision
	var following bool
	for {
		resp, err := c.client.Get(context.Background(),
			string(start),
			etcd.WithRange(end),
			etcd.WithLimit(1024),
			etcd.WithMaxModRev(currentRev),
			etcd.WithSerializable())
		if err != nil {
			return fmt.Errorf("get start %v: %s", string(start), err)
		}
		if following && len(resp.Kvs) > 0 {
			resp.Kvs = resp.Kvs[1:]
		}
		if len(resp.Kvs) == 0 {
			break
		}
		for _, kv := range resp.Kvs {
			if !handler(kv.Key, kv.Value) {
				return nil
			}
		}
		start = resp.Kvs[len(resp.Kvs)-1].Key
		following = true
	}
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Inspect the wrapped error: for timeouts, check etcd disk latency (`etcdctl endpoint health -w table`) and tune backend
Retry/restart the scan — the paging design tolerates re-scanning from the start key
Reduce scan pressure (increase max-removals/intervals) or scale the etcd cluster
Ensure stable network between the JuiceFS client and etcd

Defensive patterns

Strategy: retry

Validate before calling

// Check etcd serializable-read latency and health before long maintenance jobs
etcdctl endpoint health -w table

Try / catch

// Background scan failures are returned, retried by design; for your own jobs:
if err := scanJob(); err != nil {
    log.Warnf("scan page failed, will retry from %q: %v", startKey, err)
    time.Sleep(backoff)
}

Prevention

Schedule heavy scans off-peak; reduce removal batch sizes
Monitor etcd disk latency; etcd is sensitive to slow fsync
Expect and tolerate transient scan errors; make jobs idempotent

When it happens

Trigger: Background scanning (e.g. cleanup of stale session/slice keys) when a paged range Get fails: transient etcd unavailability, gRPC timeouts, or serializable read errors under load.

Common situations: etcd under heavy write load so serializable reads hit stale/slow followers; network hiccups during long scans; etcd restarts; very large key spaces making scans long-running and failure-prone.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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