weaviate/weaviate · error

rq bits is immutable: attempted change from "%v" to "%v"

Error message

rq bits is immutable: attempted change from "%v" to "%v"

What it means

When Residual Quantization (RQ) is enabled both before and after an update, the RQ bit width is immutable — changing it invalidates all stored compressed codes. The validator rejects any attempt to change RQ.Bits between the initial and updated configs.

Source

Thrown at adapters/repos/db/vector/hnsw/config_update.go:75

		{
			name:     "multivector enabled",
			accessor: func(c ent.UserConfig) interface{} { return c.Multivector.Enabled },
		},
		{
			name:     "muvera enabled",
			accessor: func(c ent.UserConfig) interface{} { return c.Multivector.MuveraConfig.Enabled },
		},
	}

	for _, u := range immutableFields {
		if err := validateImmutableField(u, initialParsed, updatedParsed); err != nil {
			return err
		}
	}

	if initialParsed.RQ.Enabled && updatedParsed.RQ.Enabled &&
		initialParsed.RQ.Bits != updatedParsed.RQ.Bits {
		return errors.Errorf("rq bits is immutable: attempted change from \"%v\" to \"%v\"",
			initialParsed.RQ.Bits, updatedParsed.RQ.Bits)
	}

	if initialParsed.RQ.Enabled && updatedParsed.RQ.Enabled &&
		initialParsed.RQ.Centering != updatedParsed.RQ.Centering {
		return errors.Errorf("rq centering is immutable: attempted change from \"%v\" to \"%v\"",
			initialParsed.RQ.Centering, updatedParsed.RQ.Centering)
	}

	return nil
}

type immutableParameter struct {
	accessor func(c ent.UserConfig) interface{}
	name     string
}

func validateImmutableField(u immutableParameter,

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Keep rq.bits at its existing value in the update request
2. If a different bit width is truly needed, re-create the collection and re-import vectors with the new compression settings
3. Disable RQ first if the API permits, then re-enable with new bits, accepting a re-compression cost where supported

Example fix

// before
{"vectorIndexConfig": {"rq": {"enabled": true, "bits": 4}}}
// after
{"vectorIndexConfig": {"rq": {"enabled": true, "bits": 8}}} // keep bits unchanged

cur := currentSchema.Classes[i].VectorIndexConfig.(ent.UserConfig)
if cur.RQ.Enabled && desired.RQ.Enabled && cur.RQ.Bits != desired.RQ.Bits {
    return errors.New("rq.bits is immutable; recreate the collection to change it")
}

if err := client.Schema().Updater().WithClass(updated).Do(ctx); err != nil {
    if strings.Contains(err.Error(), "rq bits is immutable") {
        // fall back: keep existing bits or recreate collection
    }
}

When it happens

Trigger: Calling ValidateUserConfigUpdate (via ValidateVectorIndexConfigUpdate or the schema PATCH endpoint) where initialParsed.RQ.Enabled && updatedParsed.RQ.Enabled && initialParsed.RQ.Bits != updatedParsed.RQ.Bits.

Common situations: A developer PATCHes the collection schema trying to tune rq.bits (e.g. from 8 to 4) on a compressed collection; infrastructure-as-code drift re-applies an older config with different rq.bits.

Related errors

• rq centering is immutable: attempted change from "%v" to "%v
• compress command cannot be executed before inserting some da
• compressing vectors: %w
• invalid hnsw config: more than a single compression methods
• invalid hnsw config: rq centering is not supported for multi

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