weaviate/weaviate · error

failed to get bucket

Error message

failed to get bucket

What it means

setDimensions writes the vector dimension count into the 'dimensions' key of the metadata bucket inside a bolt write transaction. If the bucket (created earlier by restoreMetadata) is not present in the transaction, the code aborts with this error, wrapped as 'set dimensions'.

Source

Thrown at adapters/repos/db/vector/flat/metadata.go:275

		if i > maxCursorSize {
			break
		}
		i++
	}
	return 0
}

func (index *flat) setDimensions(dimensions int32) error {
	err := index.openMetadata()
	if err != nil {
		return err
	}
	defer index.closeMetadata()

	err = index.metadata.Update(func(tx *bolt.Tx) error {
		b := tx.Bucket([]byte(vectorMetadataBucket))
		if b == nil {
			return errors.New("failed to get bucket")
		}
		buf := make([]byte, 4)
		binary.LittleEndian.PutUint32(buf, uint32(dimensions))
		return b.Put([]byte("dimensions"), buf)
	})
	if err != nil {
		return errors.Wrap(err, "set dimensions")
	}

	return nil
}

// RQ data persistence and restoration functions

func (index *flat) persistRQData() error {
	if index.quantizer == nil || index.compressionType == CompressionBQ {
		return nil
	}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Ensure restoreMetadata() (which creates the bucket) runs before setDimensions in the startup path.
2. If the metadata file is missing the bucket, delete the shard and let the index rebuild/recalculate dimensions from stored vectors.
3. Restore metadata.db from backup if it was accidentally replaced or truncated.
4. Upgrade weaviate if this stems from an older write-order bug; the current code creates the bucket before use.

// Ensure bucket creation happened before any setDimensions call
err := meta.Update(func(tx *bolt.Tx) error {
    if tx.Bucket([]byte("vector_metadata")) == nil {
        return errors.New("metadata bucket missing; run restoreMetadata first")
    }
    return nil
})

if err := idx.SetDimensions(dims); err != nil {
    if strings.Contains(err.Error(), "set dimensions") {
        // re-run restore to (re)create the bucket, then retry once
        if rErr := idx.RestoreMetadata(); rErr != nil { return rErr }
        return idx.SetDimensions(dims)
    }
    return err
}

When it happens

Trigger: index.setDimensions(dims) is called (from initDimensions backwards-compatibility path when the stored dims value is missing) but tx.Bucket(vectorMetadataBucket) returns nil — i.e. the bucket was never created or the metadata DB was reopened/reset.

Common situations: Starting a flat index whose metadata.db was truncated or recreated without restoreMetadata running first; a crash between openMetadata and bucket creation; manually replaced metadata files.

Related errors

• failed to create or get bucket
• create dimensions bucket: %w
• unable to set max posting size
• min posting size must be less than max posting size
• aggregate sparse search: %w

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/f5f324cf95d95f5a. Report an issue: GitHub.