vitessio/vitess · error

failed to parse tablet_alias %s: %w

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.

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)

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

• invalid tablet alias: '%s', expecting format: '%s'
• CreateKeyspace(%+v) failed to acquire topoRWPool: %w
• CreateShard(%+v) failed to acquire topoRWPool: %w
• FindAllShardsInKeyspace(cluster = %s, keyspace = %s) failed:
• RefreshState(%v) failed to acquire topoReadPool: %w

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