vitessio/vitess · error

invalid tablet alias: '%s', expecting format: '%s'

Error message

invalid tablet alias: '%s', expecting format: '%s'

What it means

ParseTabletAlias expects an alias of the form <cell>-<uid> (e.g. zone1-100), validated by a regular expression. The input did not match the expected pattern, so no alias could be built. Note that a syntactically matching alias with a bad UID raises a different wrapped error.

Source

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

// TabletAliasString formats a TabletAlias
func TabletAliasString(ta *topodatapb.TabletAlias) string {
	if ta == nil {
		return "<nil>"
	}
	return fmt.Sprintf("%v-%010d", ta.Cell, ta.Uid)
}

const tabletAliasFormat = "^(?P<cell>[-_.a-zA-Z0-9]+)-(?P<uid>[0-9]+)$"

var tabletAliasRegexp = regexp.MustCompile(tabletAliasFormat)

// ParseTabletAlias returns a TabletAlias for the input string,
// of the form <cell>-<uid>
func ParseTabletAlias(aliasStr string) (*topodatapb.TabletAlias, error) {
	nameParts := tabletAliasRegexp.FindStringSubmatch(aliasStr)
	if len(nameParts) != 3 {
		return nil, fmt.Errorf("invalid tablet alias: '%s', expecting format: '%s'", aliasStr, tabletAliasFormat)
	}
	uid, err := ParseUID(nameParts[tabletAliasRegexp.SubexpIndex("uid")])
	if err != nil {
		return nil, vterrors.Wrapf(err, "invalid tablet uid in alias '%s'", aliasStr)
	}
	return &topodatapb.TabletAlias{
		Cell: nameParts[tabletAliasRegexp.SubexpIndex("cell")],
		Uid:  uid,
	}, nil
}

// ParseTabletSet returns a set of tablets based on a provided comma separated list of tablets.
func ParseTabletSet(tabletListStr string) sets.Set[string] {
	set := sets.New[string]()
	if tabletListStr == "" {
		return set
	}
	list := strings.Split(tabletListStr, ",")

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Use the format cell-uid, e.g. zone1-100, matching the alias shown by vtctldclient GetTablets
2. Strip whitespace/newlines from the value (shell quoting or tr -d '\r')
3. Use the correct separator: hyphen between cell and UID, not underscore or dot

Example fix

// before
vtctldclient GetPermissions zone1_100
// after
vtctldclient GetPermissions zone1-100

if !regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9.-]*-[0-9]+$`).MatchString(alias) {
    return fmt.Errorf("alias %q must be <cell>-<uid>", alias)
}

func looksLikeTabletAlias(s string) bool {
    return regexp.MustCompile(`^[^-]+-[0-9]+$`).MatchString(strings.TrimSpace(s))
}

alias, err := topoproto.ParseTabletAlias(input)
if err != nil {
    return fmt.Errorf("bad tablet alias %q: %w", input, err)
}

When it happens

Trigger: Passing a string without the cell-uid form to ParseTabletAlias — e.g. '100', 'zone1_100', 'zone1-100-0', empty string — via commands like Backup, RestoreFromBackup, ExecuteFetchAsDBA, GetPermissions, or TabletAliasesFromPosArgs.

Common situations: Using underscore instead of hyphen; omitting the cell prefix; passing a hostname or IP; trailing whitespace or CR from copied config values; case where the cell name contains characters the regexp disallows.

Related errors

• served_type has to be in the serving graph, not %v
• unknown keyspace type: %v
• invalid shard path: %v
• unknown TabletType %v
• failed to parse tablet_alias %s: %w

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