{"record":{"id":"dac91578686c8f46","repo":"etcd-io/etcd","slug":"lease-id-must-be-8-byte","errorCode":null,"errorMessage":"lease ID must be 8-byte","messagePattern":"lease ID must be 8-byte","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tools/etcd-dump-db/backend.go","lineNumber":83,"sourceCode":"\t\"meta\":      metaDecoder,\n}\n\nfunc defaultDecoder(k, v []byte) {\n\tfmt.Printf(\"key=%q, value=%q\\n\", k, v)\n}\n\nfunc keyDecoder(k, v []byte) {\n\trev := mvcc.BytesToBucketKey(k)\n\tvar kv mvccpb.KeyValue\n\tif err := proto.Unmarshal(v, &kv); err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Printf(\"rev=%+v, value=[key %q | val %q | created %d | mod %d | ver %d]\\n\", rev, string(kv.Key), string(kv.Value), kv.CreateRevision, kv.ModRevision, kv.Version)\n}\n\nfunc bytesToLeaseID(bytes []byte) int64 {\n\tif len(bytes) != 8 {\n\t\tpanic(fmt.Errorf(\"lease ID must be 8-byte\"))\n\t}\n\treturn int64(binary.BigEndian.Uint64(bytes))\n}\n\nfunc leaseDecoder(k, v []byte) {\n\tleaseID := bytesToLeaseID(k)\n\tvar lpb leasepb.Lease\n\tif err := proto.Unmarshal(v, &lpb); err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Printf(\"lease ID=%016x, TTL=%ds, remaining TTL=%ds\\n\", leaseID, lpb.TTL, lpb.RemainingTTL)\n}\n\nfunc authDecoder(k, v []byte) {\n\tif string(k) == \"authRevision\" {\n\t\trev := binary.BigEndian.Uint64(v)\n\t\tfmt.Printf(\"key=%q, value=%v\\n\", k, rev)\n\t} else {","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/etcd-io/etcd/blob/f744d457f484e9f748a0700b48ef96dcf792df33/tools/etcd-dump-db/backend.go#L65-L101","documentation":"etcd-dump-db decodes records in the 'lease' bucket by converting each bbolt key to an int64 lease ID, which etcd always serializes as exactly 8 big-endian bytes. bytesToLeaseID panics when the key length differs, meaning the tool encountered a record in the lease bucket that is not a lease key — i.e. the data dir's layout does not match what this tool version expects, or the bucket content is corrupted.","triggerScenarios":"Running `etcd-dump-db iterate-leases --data-dir ...` (the command that routes keys through leaseDecoder) against a db whose lease bucket holds keys of a length other than 8; typically an etcd-dump-db binary built from a different release than the server that wrote the data dir.","commonSituations":"Using a stale tools/ checkout of etcd-dump-db against a data dir from a newer/older etcd; pointing --data-dir at the wrong subdirectory (e.g. member/wal leftover or a snap dir holding non-lease pages); a genuinely corrupted db file from an unclean shutdown.","solutions":["Rebuild/reinstall etcd-dump-db from the same etcd source tree and version as the server that produced the data dir (make build-tools from the matching tag).","Double-check the --data-dir path points at the member's data dir (containing member/snap/db), not a parent or sibling directory.","Validate the db before dumping: `etcdutl bbolt check <data-dir>/member/snap/db` to rule out corruption.","If dumping another bucket was intended, use the iterate/dump subcommand without the lease decoder instead of iterate-leases."],"exampleFix":"// before (tool built from wrong version, panics on lease bucket):\n//   etcd-dump-db iterate-leases --data-dir /var/lib/etcd-wrong\n\n// after\n//   git checkout v3.5.X && go install ./tools/etcd-dump-db\n//   etcd-dump-db iterate-leases --data-dir /var/lib/etcd","handlingStrategy":"validation","validationCode":"// Guard before decoding (if embedding the tool's logic):\nfunc safeBytesToLeaseID(b []byte) (int64, bool) {\n\tif len(b) != 8 {\n\t\treturn 0, false\n\t}\n\treturn int64(binary.BigEndian.Uint64(b)), true\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build etcd-dump-db from the same etcd release tag as the server that wrote the data dir.","Point --data-dir at the member data dir containing member/snap/db.","Run `etcdutl bbolt check` on the db before offline inspection.","Prefer `etcd-dump-db list-bucket` first to confirm bucket layout matches expectations."],"tags":["etcd-dump-db","lease","offline-tool","version-skew"],"backgroundTag":null,"analyzedSha":"f744d457f484e9f748a0700b48ef96dcf792df33","analyzedAt":"2026-08-15T09:39:50.079Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}