vitessio/vitess · error

UnicodeLooseXXHash.Verify: %v

Error message

UnicodeLooseXXHash.Verify: %v

What it means

UnicodeLooseXXHash.Verify behaves like UnicodeLooseMD5.Verify but hashes with the unicode collation + xxhash; any Hash failure (non-bytes-convertible value or invalid UTF-8) is wrapped as 'UnicodeLooseXXHash.Verify: %v'. It means one of the ids supplied for verification cannot be normalized by the unicode collator.

Source

Thrown at go/vt/vtgate/vindexes/unicodeloosexxhash.go:78

}

// IsUnique returns true since the Vindex is unique.
func (vind *UnicodeLooseXXHash) IsUnique() bool {
	return true
}

// NeedsVCursor satisfies the Vindex interface.
func (vind *UnicodeLooseXXHash) NeedsVCursor() bool {
	return false
}

// Verify returns true if ids maps to ksids.
func (vind *UnicodeLooseXXHash) Verify(ctx context.Context, vcursor VCursor, ids []sqltypes.Value, ksids [][]byte) ([]bool, error) {
	out := make([]bool, 0, len(ids))
	for i, id := range ids {
		data, err := vind.Hash(id)
		if err != nil {
			return nil, fmt.Errorf("UnicodeLooseXXHash.Verify: %v", err)
		}
		out = append(out, bytes.Equal(data, ksids[i]))
	}
	return out, nil
}

// Map can map ids to key.ShardDestination objects.
func (vind *UnicodeLooseXXHash) Map(ctx context.Context, vcursor VCursor, ids []sqltypes.Value) ([]key.ShardDestination, error) {
	out := make([]key.ShardDestination, 0, len(ids))
	for _, id := range ids {
		data, err := vind.Hash(id)
		if err != nil {
			return nil, fmt.Errorf("UnicodeLooseXXHash.Map: %v", err)
		}
		out = append(out, key.DestinationKeyspaceID(data))
	}
	return out, nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Find the offending row/value and verify it with a UTF-8 validity check.
2. Enforce utf8mb4 charset on the column and connections.
3. Re-encode or clean the invalid data.
4. Switch the vindex to a hash/binary variant if the data is not really unicode text.
5. Ensure only string values are supplied to Verify from tooling.

Example fix

// before
WHERE name = 0xFF -- hex literal on unicode_loose_xxhash vindex
// after
WHERE name = 'café' -- valid utf8mb4 string

if !utf8.Valid(idBytes) {
    return errors.New("unicode_loose_xxhash requires valid UTF-8 ids")
}

ok, err := vindex.Verify(ctx, vc, ids, ksids)
if err != nil {
    return fmt.Errorf("verify failed: %w", err) // inspect for invalid UTF-8 cause
}

When it happens

Trigger: Verify invoked with ids[i] that cannot ToBytes() or contains bytes that are not valid UTF-8, typically while validating vindex ownership during a routed write or VReplication vindex check.

Common situations: Non-UTF8 client charset writing to a unicode_loose_xxhash column; binary/blobs mapped to this vindex; corrupted data from direct MySQL writes bypassing VTGate.

Related errors

• UnicodeLooseXXHash.Map: %v
• UnicodeLooseMD5.Verify: %v
• UnicodeLooseMD5.Map: %v
• Binary.ReverseMap: keyspaceId is nil
• cannot map vindex to unique keyspace id: %v

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