weaviate/weaviate · error

write metadata

Error message

write metadata

What it means

Wraps a failure from writeMetadata during snapshot Flush. Metadata (format version, flags, compression/Muvera settings, node count) is the snapshot header; failing here means the header could not be encoded into the metadata buffer.

Source

Thrown at adapters/repos/db/vector/hnsw/compact/snapshot_writer.go:279

// is always removed, including on the error paths.
func (s *SnapshotWriter) Flush() error {
	if s.body != nil {
		defer s.body.close()
	}
	if s.firstErr != nil {
		return s.firstErr
	}

	var nodeCount uint32
	if s.body != nil {
		if err := s.body.finish(); err != nil {
			return errors.Wrap(err, "finalize snapshot body")
		}
		nodeCount = uint32(s.body.count)
	}

	if err := s.writeMetadata(nodeCount); err != nil {
		return errors.Wrap(err, "write metadata")
	}

	if s.body != nil && nodeCount > 0 {
		if err := s.body.copyTo(s.w); err != nil {
			return errors.Wrap(err, "write body")
		}
	}

	return nil
}

// writeMetadata writes the snapshot metadata header. nodeCount is the total
// slot count (maxNodeID+1), sized so the reader can pre-allocate Graph.Nodes.
func (s *SnapshotWriter) writeMetadata(nodeCount uint32) error {
	var buf bytes.Buffer

	// Metadata content
	_ = writeUint64(&buf, s.entrypoint)

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Read the wrapped cause — it will point at writeCompressionData or writeMuveraData.
2. If compression-related, verify PQ/BQ/SQ compression settings on the shard are fully initialized before exporting the snapshot.
3. If Muvera-related, check the multi-vector/Muvera configuration is valid; disable Muvera encoding if not needed and retry.
4. Discard the partial snapshot output and re-run Flush on a fresh writer; the target file is invalid after a metadata failure.

// confirm compression and Muvera config are fully initialized before writing
if shard.HasCompression() && !shard.CompressionReady() { return errors.New("compression not initialized") }

if err := writer.Flush(); err != nil {
    var wrapped interface{ Unwrap() error }
    if errors.As(err, &wrapped) { log.Printf("metadata write cause: %v", wrapped) }
    return err
}

When it happens

Trigger: Calling Flush when writeCompressionData or writeMuveraData inside writeMetadata fails (see 6186/6187), or internal buffer encoding panics/fails due to unsupported compression or Muvera state.

Common situations: Snapshot writer configured with compression whose parameters could not be serialized; Muvera (multi-vector encoding) state partially initialized; version skew where a newer field cannot be encoded by this build.

Related errors

• read RQ swap J
• read RQ sign
• read BRQ inputDim
• read BRQ outputDim
• read BRQ rounds

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