What causes "region_bytes must be 1 or 2: %v" in vitessio/vitess?

Set region_bytes to 1 or 2 in the vindex's JSON configuration.

region_bytes must be 1 or 2: %v

Error message

region_bytes must be 1 or 2: %v

What it means

RegionJSON is configured via a vschema 'region_bytes' parameter that must be exactly 1 or 2, since the region is encoded in 1 or 2 bytes of the keyspace id. Any other value (0, 3, negative, wrong type) makes vindex creation fail with this error.

Source

Thrown at go/vt/vtgate/vindexes/region_json.go:89

	rmPath := m[regionJSONParamRegionMap]
	rmap := make(map[string]uint64)
	data, err := os.ReadFile(rmPath)
	if err != nil {
		return nil, err
	}
	log.Info("Loaded Region map from: " + rmPath)
	err = json.Unmarshal(data, &rmap)
	if err != nil {
		return nil, err
	}
	rb, err := strconv.Atoi(m[regionJSONParamRegionBytes])
	if err != nil {
		return nil, err
	}
	switch rb {
	case 1, 2:
	default:
		return nil, fmt.Errorf("region_bytes must be 1 or 2: %v", rb)
	}

	return &RegionJSON{
		name:          name,
		regionMap:     rmap,
		regionBytes:   rb,
		unknownParams: FindUnknownParams(m, regionJSONParams),
	}, nil
}

// String returns the name of the vindex.
func (rv *RegionJSON) String() string {
	return rv.name
}

// Cost returns the cost of this index as 1.
func (rv *RegionJSON) Cost() int {
	return 1

View on GitHub (pinned to 01a25a7d17)

Solutions

Set region_bytes to 1 or 2 in the vindex's JSON configuration.
Validate the vschema JSON before applying it (vtctldclient ApplyVSchema validates this).
Re-apply the corrected vschema.

Example fix

// before
{"type": "region_json", "params": {"region_bytes": "4"}}
// after
{"type": "region_json", "params": {"region_bytes": "1"}}

Defensive patterns

Strategy: validation

Validate before calling

if rb != 1 && rb != 2 {
    return fmt.Errorf("region_bytes must be 1 or 2, got %v", rb)
}

Type guard

func validRegionBytes(v any) bool {
    rb, ok := v.(int)
    return ok && (rb == 1 || rb == 2)
}

Prevention

Validate vschema JSON before applying it.
Keep vindex parameter defaults documented for your team.
Add a config lint that checks region_bytes ∈ {1,2} for region_json vindexes.

When it happens

Trigger: Creating/loading a region_json vindex whose JSON parameters include region_bytes set to a value other than 1 or 2 (e.g. omitted-and-typed incorrectly, 0, or 8).

Common situations: Copy-pasted vschema config with region_bytes: 4; misunderstanding that region_bytes means total keyspace length instead of the region prefix width; typo feeding a string into the integer field.

Related errors

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