vitessio/vitess · error

invalid keyspace id

Error message

invalid keyspace id: %v

What it means

ReverseBits.unreverse expects keyspace ids of exactly 8 bytes (bit-reversed uint64). A different length cannot be a valid ReverseBits keyspace id, so reversal fails with this hex-encoded diagnostic. It guards ReverseMap against ids produced by other vindexes or corrupt data.

Solutions

1. Ensure the vindex used for reversal is the same one that generated the keyspace ids (reverse_bits produces 8-byte ids).
2. Fix vschema if the table actually uses binary/unicode vindexes.
3. Rebuild lookup data containing truncated or foreign keyspace ids.

if len(ksid) != 8 {
    return fmt.Errorf("expected 8-byte reverse_bits keyspace id, got %d bytes", len(ksid))
}

func isReverseBitsKeyspaceID(k []byte) bool { return len(k) == 8 }

When it happens

Trigger: ReverseMap on a reverse_bits vindex receives a keyspace id whose length != 8 — e.g. ids from a binary_md5 (16-byte) vindex or truncated keys in a lookup table.

Common situations: Wrong vindex type in vschema after a migration; lookup tables populated by a different vindex; manual test fixtures with short/long ids.

Related errors

• Numeric.ReverseMap: length of keyspaceId is not 8
• could not map to a keyspace id, got destination
• mapping row to keyspace id returned an invalid array of…
• a conflicting table named
• a conflicting vindex named

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/022587e2ae680db5. Report an issue: GitHub.

Appendix: source

Thrown at go/vt/vtgate/vindexes/reverse_bits.go:137

	if err != nil {
		return nil, err
	}
	return reverse(num), nil
}

func init() {
	Register("reverse_bits", newReverseBits)
}

func reverse(shardKey uint64) []byte {
	reversed := make([]byte, 8)
	binary.BigEndian.PutUint64(reversed, bits.Reverse64(shardKey))
	return reversed
}

func unreverse(k []byte) (uint64, error) {
	if len(k) != 8 {
		return 0, fmt.Errorf("invalid keyspace id: %v", hex.EncodeToString(k))
	}
	return bits.Reverse64(binary.BigEndian.Uint64(k)), nil
}

View on GitHub (pinned to 01a25a7d17)