What causes "unsupported PQ encoder type %d" in weaviate/weaviate?

Upgrade to the Weaviate version that wrote the snapshot so the new encoder type is understood.

unsupported PQ encoder type %d

Error message

unsupported PQ encoder type %d

What it means

Inside PQ (product quantization) snapshot data, readPQData dispatches on the encoder type stored per-compressor. Only the tile encoder and KMeans encoder are supported; any other value cannot be deserialized and aborts the read.

Source

Thrown at adapters/repos/db/vector/hnsw/compact/snapshot_reader.go:351

	pqData := &compression.PQData{
		Dimensions:          dims,
		EncoderType:         compression.Encoder(encoderType),
		Ks:                  ks,
		M:                   m,
		EncoderDistribution: dist,
		UseBitsEncoding:     useBitsEncoding != 0,
	}

	// Read encoders
	var encoderReader func(io.Reader, *compression.PQData, uint16) (compression.PQSegmentEncoder, error)
	switch pqData.EncoderType {
	case compression.UseTileEncoder:
		encoderReader = readSnapshotTileEncoder
	case compression.UseKMeansEncoder:
		encoderReader = readSnapshotKMeansEncoder
	default:
		return fmt.Errorf("unsupported PQ encoder type %d", encoderType)
	}

	for i := uint16(0); i < m; i++ {
		encoder, err := encoderReader(reader, pqData, i)
		if err != nil {
			return errors.Wrapf(err, "read PQ encoder %d", i)
		}
		pqData.Encoders = append(pqData.Encoders, encoder)
	}

	res.SetCompressionPQData(pqData)
	return nil
}

// readSnapshotTileEncoder reads a tile encoder from the snapshot.
func readSnapshotTileEncoder(reader io.Reader, data *compression.PQData, i uint16) (compression.PQSegmentEncoder, error) {
	bins, err := readSnapshotFloat64(reader)
	if err != nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

Upgrade to the Weaviate version that wrote the snapshot so the new encoder type is understood.
Delete the snapshot and let the PQ-compressed index regenerate from the commitlog.
Recreate the collection/compression configuration so a supported encoder (tile or KMeans) is used, then rebuild the index.

Defensive patterns

Strategy: validation

Validate before calling

// Before loading PQ snapshots, confirm the encoder type in the collection config
// is one supported by this build (tile or KMeans):
// if cfg.PQ.Encoder.Type not in {tile, kmeans} -> rebuild instead of loading

Type guard

func isSupportedPQEncoder(e uint8) bool {
	return e == compression.UseTileEncoder || e == compression.UseKMeansEncoder
}

Try / catch

if err != nil && strings.Contains(err.Error(), "unsupported PQ encoder type") {
	return fmt.Errorf("snapshot PQ encoder unknown to this build; upgrade or re-compress index: %w", err)
}

Prevention

Avoid downgrading Weaviate on collections using PQ compression.
Standardize PQ encoder settings (tile/kmeans) across environments.
Rebuild the index from vectors if a snapshot's encoder is unrecognized.

When it happens

Trigger: SnapshotReader.Read on a compressed snapshot whose PQ section encodes an encoder-type byte other than UseTileEncoder or UseKMeansEncoder — from a newer writer version, a corrupted (checksum-passing but semantically wrong) metadata blob, or a test fixture with a bogus value.

Common situations: Downgrade across releases that added a new PQ encoder type; or replaying a snapshot produced on another cluster with an incompatible build.

Related errors

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