vitessio/vitess · error

unknown TabletType %v

Error message

unknown TabletType %v

What it means

ParseTabletType could not map the input string to a topodatapb.TabletType enum value. Valid types include PRIMARY, REPLICA, RDONLY, SPARE, BACKUP, RESTORE, DRAINED, EXPERIMENTAL (case-insensitive). This is a client-side validation error before any topo operation.

Source

Thrown at go/vt/topo/topoproto/tablet.go:177

// AllTabletTypes lists all the possible tablet types
var AllTabletTypes = []topodatapb.TabletType{
	topodatapb.TabletType_PRIMARY,
	topodatapb.TabletType_REPLICA,
	topodatapb.TabletType_RDONLY,
	topodatapb.TabletType_BATCH,
	topodatapb.TabletType_SPARE,
	topodatapb.TabletType_EXPERIMENTAL,
	topodatapb.TabletType_BACKUP,
	topodatapb.TabletType_RESTORE,
	topodatapb.TabletType_DRAINED,
}

// ParseTabletType parses the tablet type into the enum.
func ParseTabletType(param string) (topodatapb.TabletType, error) {
	value, ok := topodatapb.TabletType_value[strings.ToUpper(param)]
	if !ok {
		return topodatapb.TabletType_UNKNOWN, fmt.Errorf("unknown TabletType %v", param)
	}
	return topodatapb.TabletType(value), nil
}

// ParseTabletTypes parses a comma separated list of tablet types and returns a slice with the respective enums.
func ParseTabletTypes(param string) ([]topodatapb.TabletType, error) {
	var tabletTypes []topodatapb.TabletType
	if param == "" {
		return tabletTypes, nil
	}
	for typeStr := range strings.SplitSeq(param, ",") {
		t, err := ParseTabletType(typeStr)
		if err != nil {
			return nil, err
		}
		tabletTypes = append(tabletTypes, t)
	}
	return tabletTypes, nil

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Use an exact valid type name: PRIMARY, REPLICA, RDONLY, SPARE, BACKUP, RESTORE, DRAINED
2. If migrating from older Vitess, replace 'master' with 'PRIMARY' (or the version-appropriate term)
3. Verify shell variables actually contain the type value (echo before running)

Example fix

// before
vtctldclient ChangeTabletType zone1-100 master
// after
vtctldclient ChangeTabletType zone1-100 primary

switch strings.ToUpper(tt) {
case "PRIMARY", "REPLICA", "RDONLY", "SPARE", "BACKUP", "RESTORE", "DRAINED", "EXPERIMENTAL":
    // ok
default:
    return fmt.Errorf("unknown tablet type %q", tt)
}

func isValidTabletType(s string) bool {
    _, ok := topodatapb.TabletType_value[strings.ToUpper(s)]
    return ok
}

tt, err := topoproto.ParseTabletType(typeFlag)
if err != nil {
    return fmt.Errorf("bad type %q: %w", typeFlag, err)
}

When it happens

Trigger: Passing an unrecognized string to ParseTabletType — via vtctldclient ChangeTabletType, SetShardTabletControl, or parsing destination types — e.g. 'master' on a version expecting 'PRIMARY', 'readonly' (should be RDONLY), empty string.

Common situations: Using the pre-Vitess-9 term 'master' with newer tooling or vice versa; abbreviating 'replica' as 'r'; lowercase config values that should still work (they do — case-insensitive) but misspellings do not; shell variables expanding empty.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• served_type has to be in the serving graph, not %v
• unknown keyspace type: %v
• invalid shard path: %v
• invalid tablet alias: '%s', expecting format: '%s'
• the <tablet alias> and <db type> arguments are required for

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