microsoft/FASTER · error

Provided bucket address is invalid [%lu]

Error message

Provided bucket address is invalid [%lu]

What it means

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.

Solutions

1. Verify the source checkpoint/index file is complete and not truncated; restore from a known-good checkpoint
2. Rebuild the index (e.g. full rehash / reload data) instead of recovering the corrupt snapshot
3. Upgrade FASTER to the latest version — bucket-address reconciliation bugs have been fixed over time
4. Investigate how the bucket address became kInvalidAddress; add assertions after FASTER index operations that mutate buckets

Example fix

// before
if (bucket_address.control() == FixedPageAddress::kInvalidAddress) { ... }
// after
if (bucket_address.control() == FixedPageAddress::kInvalidAddress) {
  log_error("Invalid bucket addr %lu; rebuilding index bucket %lu", bucket_address.control(), bucket_index);
  return FixedPageAddress::kInvalidAddress; // then trigger full index rebuild upstream
}

// after loading an index / before checkpointing, validate bucket chain addresses
bool index_sane = true;
for (each bucket in index) {
  if (bucket.address.control() == FixedPageAddress::kInvalidAddress &&
      prev_next_of(bucket) == FixedPageAddress::kInvalidAddress) {
    index_sane = false; break;
  }
}
if (!index_sane) rebuild_index(); // instead of checkpointing corrupt state

bool IsValidBucketAddress(FixedPageAddress a) {
  return a.control() != FixedPageAddress::kInvalidAddress;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unexpected entry type
• Unable to set first valid segment to
• Unable to set last valid segment to
• Can spin-wait for commit (checkpoint completion) only if…
• Make sure all async operations issued on this session are…

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/0382784bbcaac499. Report an issue: GitHub.

Appendix: source

Thrown at cc/src/index/mem_index.h:497

    return true;
  }

  static FixedPageAddress UnsafeFreeBucket(overflow_buckets_allocator_t& overflow_buckets_allocator_,
                                           FixedPageAddress bucket_address, hash_bucket_t* previous) {
    FixedPageAddress current_bucket_address{ FixedPageAddress::kInvalidAddress };
    if (previous != nullptr) {
      // retrieve bucket address
      current_bucket_address = previous->overflow_entry.load().address();
      // mark overflow entry of previous bucket
      previous->overflow_entry.store(HashBucketEntry::kInvalidEntry);
    }

    if (bucket_address.control() == FixedPageAddress::kInvalidAddress) {
      if (current_bucket_address.control() != FixedPageAddress::kInvalidAddress) {
        // use prev->next address to populate missing bucket_address value
        bucket_address = current_bucket_address;
      } else {
        log_error("Provided bucket address is invalid [%lu]", bucket_address.control());
        return FixedPageAddress::kInvalidAddress;
      }
    } else if (current_bucket_address.control() != FixedPageAddress::kInvalidAddress) {
      log_warn("Bucket addresses differ [prev->next: %lu, curr: %lu]",
               current_bucket_address.control(), bucket_address.control());
    }

    // store the address of next bucket (if any)
    FixedPageAddress next_address;
    hash_bucket_t* current = &overflow_buckets_allocator_.Get(bucket_address);
    HashBucketOverflowEntry overflow_entry{ current->overflow_entry.load() };
    if (!overflow_entry.unused()) {
      next_address = overflow_entry.address();
    }
    // free current bucket
    overflow_buckets_allocator_.FreeAtEpoch(bucket_address, 0);
    return next_address;
  }

View on GitHub (pinned to 321d872eab)