weaviate/weaviate · error

could not persist dimensions

Error message

could not persist dimensions

What it means

On the first vector inserted into an HFresh index, initDimensions persists the vector dimensionality into IndexMetadata. This error wraps a failure of IndexMetadata.SetDimensions(size) — the index could not record its dimensions in metadata storage.

Source

Thrown at adapters/repos/db/vector/hfresh/insert.go:131

// initDimensions initializes dimension-dependent components (quantizer, distancer,
// posting sizes) on the first vector received. Uses a mutex+flag pattern instead of
// sync.Once so that initialization can be retried if it fails.
func (h *HFresh) initDimensions(vector []float32) error {
	h.initMu.Lock()
	defer h.initMu.Unlock()

	if h.initDone {
		return nil
	}

	size := uint32(len(vector))

	if err := h.setMaxPostingSize(size); err != nil {
		return err
	}
	if err := h.IndexMetadata.SetDimensions(size); err != nil {
		return errors.Wrap(err, "could not persist dimensions")
	}

	quantizer, err := compressionhelpers.NewBinaryRotationalQuantizer(int(size), 42, h.config.DistanceProvider)
	if err != nil {
		return errors.Wrap(err, "could not create quantizer")
	}
	h.quantizer = quantizer

	if err := h.persistQuantizationData(); err != nil {
		return errors.Wrap(err, "could not persist RQ data")
	}

	h.distancer = NewDistancer(h.quantizer, h.config.DistanceProvider)
	h.initDone = true
	atomic.StoreUint32(&h.dims, size)
	return nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check disk space and write permissions for the Weaviate data directory.
2. Inspect the wrapped SetDimensions error for the underlying storage cause.
3. initDimensions is retryable (mutex+flag pattern), so retry the insert after the storage issue is fixed.
4. If the metadata store is corrupted, recreate the collection or restore from backup.

if len(vector) == 0 {
    return errors.New("refusing to insert empty vector: index dims would be 0")
}

When it happens

Trigger: First insert into a fresh HFresh index (via Add or AddMulti) where writing the dimensions to the index metadata store fails.

Common situations: Disk full, metadata bucket unavailable, corrupted or unwritable index metadata store on first import into a new collection.

Related errors

• store muvera data in index metadata
• could not persist RQ data
• failed to upsert new centroid %d
• put muvera vector into bucket
• invalid range value while restoring SQ settings

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