vitessio/vitess · error

failed to parse tablet_alias

Error message

failed to parse tablet_alias %s: %w

What it means

Thrown by parseTablet in the vtadmin cluster package when topoproto.ParseTabletAlias cannot parse the alias string associated with a tablet discovered in a cell. The alias string must have the canonical form "<cell>-<uid>" (e.g. "zone1-100"); anything malformed fails. The wrapped error from ParseTabletAlias gives the specific parsing cause.

Solutions

1. Inspect the alias string in the error message and fix the tablet record in the topo server so it matches the "<cell>-<uid>" format (e.g. via vtctl DeleteTablet + re-init, or by correcting the record).
2. Run `vtctl GetTablets <cell>` to list aliases and find the malformed one before vtadmin reads it.
3. If the record is stale/orphaned, delete it: `vtctl DeleteTablet <bad-alias>`.
4. Verify all cells' topo data was written by the same Vitess version (no mixed-version topo corruption).

Example fix

// before (malformed alias in topo data)
alias = "zone1_100" // underscore instead of dash
// after
topotablet.Alias, err = topoproto.ParseTabletAlias("zone1-100") // valid <cell>-<uid>

alias := "zone1-100"
parts := strings.SplitN(alias, "-", 2)
valid := len(parts) == 2 && parts[0] != "" && func() bool {
	_, err := strconv.ParseUint(parts[1], 10, 32)
	return err == nil
}()
if !valid {
	return fmt.Errorf("malformed tablet alias %q, want <cell>-<uid>", alias)
}

func isWellFormedTabletAlias(alias string) bool {
	_, err := topoproto.ParseTabletAlias(alias)
	return err == nil
}

When it happens

Trigger: Calling cluster methods that discover tablets (via parseTablets, e.g. GetTablets) when the vtadmin tablet cache/etcd2 data contains an alias string that is not "<cell>-<uid>" — e.g. missing dash, non-numeric uid, or empty alias.

Common situations: Corrupted or hand-edited topo data; older topo records written by a different Vitess version with a different alias format; scripts that manually insert tablet records into the topo server; a cell name containing characters that break the alias format.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• CreateKeyspace(%+v) failed to acquire topoRWPool
• CreateShard(%+v) failed to acquire topoRWPool
• error parsing
• FindAllShardsInKeyspace
• invalid tablet alias

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

Appendix: source

Thrown at go/vt/vtadmin/cluster/cluster.go:329

	tablet := &vtadminpb.Tablet{
		Cluster: &vtadminpb.Cluster{
			Id:   c.ID,
			Name: c.Name,
		},
		Tablet: &topotablet,
	}

	topotablet.Type, err = topoproto.ParseTabletType(tabletTypeStr)
	if err != nil {
		return nil, err
	}

	tablet.State = vtadminproto.ParseTabletServingState(servingStateStr)

	topotablet.Alias, err = topoproto.ParseTabletAlias(aliasStr)
	if err != nil {
		return nil, fmt.Errorf("failed to parse tablet_alias %s: %w", aliasStr, err)
	}

	if topotablet.Alias.Cell != cell {
		// (TODO:@amason) ???
		log.Warn(fmt.Sprintf("tablet cell %s does not match alias %s. ignoring for now", cell, topoproto.TabletAliasString(topotablet.Alias)))
	}

	if mtstStr != "" {
		timeTime, err := time.Parse(time.RFC3339, mtstStr)
		if err != nil {
			return nil, fmt.Errorf("failed parsing primary_term_start_time %s: %w", mtstStr, err)
		}

		topotablet.PrimaryTermStartTime = protoutil.TimeToProto(timeTime)
	}

	if c.TabletFQDNTmpl != nil {
		tablet.FQDN, err = textutil.ExecuteTemplate(c.TabletFQDNTmpl, tablet)

View on GitHub (pinned to 01a25a7d17)