{"record":{"id":"8c9e0be81be81882","repo":"juicedata/juicefs","slug":"get-start-v-s","errorCode":null,"errorMessage":"get start %v: %s","messagePattern":"get start (.+?): (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"pkg/meta/tkv_etcd.go","lineNumber":270,"sourceCode":"\nfunc (c *etcdClient) scan(prefix []byte, handler func(key []byte, value []byte) bool) error {\n\tvar start = prefix\n\tvar end = string(nextKey(prefix))\n\tresp, err := c.client.Get(context.Background(), \"anything\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tcurrentRev := resp.Header.Revision\n\tvar following bool\n\tfor {\n\t\tresp, err := c.client.Get(context.Background(),\n\t\t\tstring(start),\n\t\t\tetcd.WithRange(end),\n\t\t\tetcd.WithLimit(1024),\n\t\t\tetcd.WithMaxModRev(currentRev),\n\t\t\tetcd.WithSerializable())\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"get start %v: %s\", string(start), err)\n\t\t}\n\t\tif following && len(resp.Kvs) > 0 {\n\t\t\tresp.Kvs = resp.Kvs[1:]\n\t\t}\n\t\tif len(resp.Kvs) == 0 {\n\t\t\tbreak\n\t\t}\n\t\tfor _, kv := range resp.Kvs {\n\t\t\tif !handler(kv.Key, kv.Value) {\n\t\t\t\treturn nil\n\t\t\t}\n\t\t}\n\t\tstart = resp.Kvs[len(resp.Kvs)-1].Key\n\t\tfollowing = true\n\t}\n\treturn nil\n}\n","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv_etcd.go#L252-L288","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Check etcd serializable-read latency and health before long maintenance jobs\netcdctl endpoint health -w table","typeGuard":null,"tryCatchPattern":"// Background scan failures are returned, retried by design; for your own jobs:\nif err := scanJob(); err != nil {\n    log.Warnf(\"scan page failed, will retry from %q: %v\", startKey, err)\n    time.Sleep(backoff)\n}","preventionTips":["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"],"tags":["etcd","scan","pagination","background","juicefs"],"backgroundTag":"database-query-failed","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}