weaviate/weaviate · error

centered 4-bit codes cap the output dimension at %d, got %d

Error message

centered 4-bit codes cap the output dimension at %d, got %d

What it means

Centered 4-bit rotational quantization stores codes with an expanded output dimension (due to padding for SIMD), and rq4CenteredMaxOutputDim caps how large that output dimension may be. rq4CheckCenteredDim rejects configurations whose outputDim exceeds this cap, since centered-RQ4 kernels and layouts are only defined up to that limit.

Source

Thrown at adapters/repos/db/vector/compressionhelpers/rq4.go:163

	}
	if len(mean) != inputDim {
		return nil, errors.Errorf("centering mean length %d does not match input dimension %d", len(mean), inputDim)
	}
	rq := NewFourBitRotationalQuantizer(inputDim, seed, distancer)
	if err := rq4CheckCenteredDim(rq.OutputDimension()); err != nil {
		return nil, err
	}
	rq.mean = mean
	rq.meanNorm2 = dotProduct(mean, mean)
	rq.layout = rq4LayoutFor(rq.OutputDimension())
	rq.metaSize = rq.layout.size
	rq.scratch.New = func() any { return newRQ4Scratch(rq.OutputDimension(), len(mean)) }
	return rq, nil
}

func rq4CheckCenteredDim(outputDim int) error {
	if outputDim > rq4CenteredMaxOutputDim {
		return errors.Errorf("centered 4-bit codes cap the output dimension at %d, got %d",
			rq4CenteredMaxOutputDim, outputDim)
	}
	return nil
}

func putUint32(b []byte, pos int, x uint32) {
	binary.BigEndian.PutUint32(b[pos:], x)
}

func getUint32(b []byte, pos int) uint32 {
	return binary.BigEndian.Uint32(b[pos:])
}

func RestoreFourBitRotationalQuantizer(inputDim int, outputDim int, rounds int, swaps [][]compression.Swap, signs [][]float32, mean []float32, distancer distancer.Provider) (*FourBitRotationalQuantizer, error) {
	// Normalize empty to nil: an uncentered quantizer must never reach the
	// SIMD dot below — the amd64 kernel faults on a nil/empty slice.
	if len(mean) == 0 {
		mean = nil

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Use plain (non-centered) FourBitRotationalQuantizer or standard RQ/PQ/BQ compression for very high-dimensional vectors
2. Reduce the embedding dimension of the model or truncate vectors before import if the application allows
3. If restoring previously-persisted state, re-create the compression config so the quantizer is rebuilt under the current cap

Example fix

// before: centered RQ4 on an over-dimensioned class
q, err := NewCenteredFourBitRotationalQuantizer(8192, seed, distancer, mean)
// after: fall back to uncentered RQ4 when the centered output dim exceeds the cap
rq := NewFourBitRotationalQuantizer(8192, seed, distancer)
if err := rq4CheckCenteredDim(rq.OutputDimension()); err != nil {
	logger.Warnf("falling back to uncentered RQ4: %v", err)
}
q, err := NewFourBitRotationalQuantizer(8192, seed, distancer)

// check the padded output dim before requesting centered RQ4
rq := NewFourBitRotationalQuantizer(inputDim, seed, distancer)
if err := rq4CheckCenteredDim(rq.OutputDimension()); err != nil {
	return fmt.Errorf("use uncentered RQ4/PQ for dim %d: %w", inputDim, err)
}

q, err := NewCenteredFourBitRotationalQuantizer(inputDim, seed, distancer, mean)
if err != nil {
	// fall back to uncentered or a different compression method
	q, err = NewFourBitRotationalQuantizer(inputDim, seed, distancer)
}

When it happens

Trigger: Creating a centered RQ4 quantizer (NewCenteredFourBitRotationalQuantizer) or restoring one (RestoreFourBitRotationalQuantizer) for a class whose vector dimension is so large that the padded output dimension exceeds rq4CenteredMaxOutputDim — i.e. very high-dimensional vectors combined with centered RQ4 compression.

Common situations: Using centered RQ4 on models with very large embedding dimensions (e.g. long-context or multi-vector embeddings); upgrading where a new cap was introduced and previously-valid persisted quantizer state no longer restores.

Related errors

• centering mean length %d does not match input dimension %d
• centering requires a non-empty mean vector
• RQ bits must be either 1 or 8
• cannot enable multiple quantization methods at the same time
• Distance not supported yet %s

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