{"record":{"id":"0382784bbcaac499","repo":"microsoft/FASTER","slug":"provided-bucket-address-is-invalid-lu","errorCode":null,"errorMessage":"Provided bucket address is invalid [%lu]","messagePattern":"Provided bucket address is invalid \\[%lu\\]","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cc/src/index/mem_index.h","lineNumber":497,"sourceCode":"    return true;\n  }\n\n  static FixedPageAddress UnsafeFreeBucket(overflow_buckets_allocator_t& overflow_buckets_allocator_,\n                                           FixedPageAddress bucket_address, hash_bucket_t* previous) {\n    FixedPageAddress current_bucket_address{ FixedPageAddress::kInvalidAddress };\n    if (previous != nullptr) {\n      // retrieve bucket address\n      current_bucket_address = previous->overflow_entry.load().address();\n      // mark overflow entry of previous bucket\n      previous->overflow_entry.store(HashBucketEntry::kInvalidEntry);\n    }\n\n    if (bucket_address.control() == FixedPageAddress::kInvalidAddress) {\n      if (current_bucket_address.control() != FixedPageAddress::kInvalidAddress) {\n        // use prev->next address to populate missing bucket_address value\n        bucket_address = current_bucket_address;\n      } else {\n        log_error(\"Provided bucket address is invalid [%lu]\", bucket_address.control());\n        return FixedPageAddress::kInvalidAddress;\n      }\n    } else if (current_bucket_address.control() != FixedPageAddress::kInvalidAddress) {\n      log_warn(\"Bucket addresses differ [prev->next: %lu, curr: %lu]\",\n               current_bucket_address.control(), bucket_address.control());\n    }\n\n    // store the address of next bucket (if any)\n    FixedPageAddress next_address;\n    hash_bucket_t* current = &overflow_buckets_allocator_.Get(bucket_address);\n    HashBucketOverflowEntry overflow_entry{ current->overflow_entry.load() };\n    if (!overflow_entry.unused()) {\n      next_address = overflow_entry.address();\n    }\n    // free current bucket\n    overflow_buckets_allocator_.FreeAtEpoch(bucket_address, 0);\n    return next_address;\n  }","sourceCodeStart":479,"sourceCodeEnd":515,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cc/src/index/mem_index.h#L479-L515","documentation":"In the checkpoint PersistentDictionary (hash index) save path, HashBucketOverflowEntryHelper tries to reconcile a bucket's prev->next address with the current bucket address read from disk. If both are invalid (kInvalidAddress), the index snapshot is corrupt/missing a bucket pointer and the helper logs this error and returns kInvalidAddress to abort processing that bucket.","triggerScenarios":"Calling Checkpoint() (or the index checkpoint save logic) when the in-memory hash index contains a bucket whose recorded address is kInvalidAddress and whose neighbor's next pointer is also invalid — i.e. an incompletely initialized or corrupted overflow/bucket chain.","commonSituations":"Recovering an index from a truncated or partially written checkpoint; a prior crash left the hash chain inconsistent; manually mutating or mis-constructing the hash index; bug in previous checkpoint that stored invalid bucket pointers.","solutions":["Verify the source checkpoint/index file is complete and not truncated; restore from a known-good checkpoint","Rebuild the index (e.g. full rehash / reload data) instead of recovering the corrupt snapshot","Upgrade FASTER to the latest version — bucket-address reconciliation bugs have been fixed over time","Investigate how the bucket address became kInvalidAddress; add assertions after FASTER index operations that mutate buckets"],"exampleFix":"// before\nif (bucket_address.control() == FixedPageAddress::kInvalidAddress) { ... }\n// after\nif (bucket_address.control() == FixedPageAddress::kInvalidAddress) {\n  log_error(\"Invalid bucket addr %lu; rebuilding index bucket %lu\", bucket_address.control(), bucket_index);\n  return FixedPageAddress::kInvalidAddress; // then trigger full index rebuild upstream\n}","handlingStrategy":"validation","validationCode":"// after loading an index / before checkpointing, validate bucket chain addresses\nbool index_sane = true;\nfor (each bucket in index) {\n  if (bucket.address.control() == FixedPageAddress::kInvalidAddress &&\n      prev_next_of(bucket) == FixedPageAddress::kInvalidAddress) {\n    index_sane = false; break;\n  }\n}\nif (!index_sane) rebuild_index(); // instead of checkpointing corrupt state","typeGuard":"bool IsValidBucketAddress(FixedPageAddress a) {\n  return a.control() != FixedPageAddress::kInvalidAddress;\n}","tryCatchPattern":null,"preventionTips":["Never checkpoint an index loaded from a truncated/partial checkpoint file","Restore from verified checkpoints (checksum the index snapshot on save/load)","Keep FASTER updated; rebuild the index rather than recovering a corrupt snapshot","Add sanity checks of bucket addresses after any custom index manipulation"],"tags":["hash-index","corruption","checkpoint","faster"],"backgroundTag":"invalid-argument-value","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}