{"record":{"id":"bfd8bcf2207bb174","repo":"weaviate/weaviate","slug":"could-not-persist-dimensions","errorCode":null,"errorMessage":"could not persist dimensions","messagePattern":"could not persist dimensions","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/vector/hfresh/insert.go","lineNumber":131,"sourceCode":"\n// initDimensions initializes dimension-dependent components (quantizer, distancer,\n// posting sizes) on the first vector received. Uses a mutex+flag pattern instead of\n// sync.Once so that initialization can be retried if it fails.\nfunc (h *HFresh) initDimensions(vector []float32) error {\n\th.initMu.Lock()\n\tdefer h.initMu.Unlock()\n\n\tif h.initDone {\n\t\treturn nil\n\t}\n\n\tsize := uint32(len(vector))\n\n\tif err := h.setMaxPostingSize(size); err != nil {\n\t\treturn err\n\t}\n\tif err := h.IndexMetadata.SetDimensions(size); err != nil {\n\t\treturn errors.Wrap(err, \"could not persist dimensions\")\n\t}\n\n\tquantizer, err := compressionhelpers.NewBinaryRotationalQuantizer(int(size), 42, h.config.DistanceProvider)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"could not create quantizer\")\n\t}\n\th.quantizer = quantizer\n\n\tif err := h.persistQuantizationData(); err != nil {\n\t\treturn errors.Wrap(err, \"could not persist RQ data\")\n\t}\n\n\th.distancer = NewDistancer(h.quantizer, h.config.DistanceProvider)\n\th.initDone = true\n\tatomic.StoreUint32(&h.dims, size)\n\treturn nil\n}\n","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/vector/hfresh/insert.go#L113-L149","documentation":"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.","triggerScenarios":"First insert into a fresh HFresh index (via Add or AddMulti) where writing the dimensions to the index metadata store fails.","commonSituations":"Disk full, metadata bucket unavailable, corrupted or unwritable index metadata store on first import into a new collection.","solutions":["Check disk space and write permissions for the Weaviate data directory.","Inspect the wrapped SetDimensions error for the underlying storage cause.","initDimensions is retryable (mutex+flag pattern), so retry the insert after the storage issue is fixed.","If the metadata store is corrupted, recreate the collection or restore from backup."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if len(vector) == 0 {\n    return errors.New(\"refusing to insert empty vector: index dims would be 0\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never insert empty vectors — they initialize index dimensions","Ensure the data directory is writable and has free space before first import","Remember initDimensions is retried on the next insert after a failure"],"tags":["vector-index","hfresh","metadata","persistence"],"backgroundTag":"metadata-persistence-failed","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}