What causes "tmclient: cannot find tablet %v" in vitessio/vitess?

Confirm the tablet UID exists in this vtcombo (check InitTabletMap output / log lines listing created tablets).

tmclient: cannot find tablet %v

Error message

tmclient: cannot find tablet %v

What it means

vtcombo implements the tablet manager client in-process: Ping looks up the target tablet in the in-memory tabletMap keyed by alias Uid. If the tablet's Uid isn't in the map (it was never created in this vtcombo, or the map changed), this error is returned instead of pinging.

Source

Thrown at go/vt/vtcombo/tablet_map.go:794

// internalTabletManagerClient implements tmclient.TabletManagerClient
type internalTabletManagerClient struct{}

func (itmc *internalTabletManagerClient) VDiff(ctx context.Context, tablet *topodatapb.Tablet, req *tabletmanagerdatapb.VDiffRequest) (*tabletmanagerdatapb.VDiffResponse, error) {
	return nil, errors.New("VDiff not implemented in vtcombo")
}

func (itmc *internalTabletManagerClient) LockTables(ctx context.Context, tablet *topodatapb.Tablet) error {
	return errors.New("not implemented in vtcombo")
}

func (itmc *internalTabletManagerClient) UnlockTables(ctx context.Context, tablet *topodatapb.Tablet) error {
	return errors.New("not implemented in vtcombo")
}

func (itmc *internalTabletManagerClient) Ping(ctx context.Context, tablet *topodatapb.Tablet) error {
	t, ok := tabletMap[tablet.Alias.Uid]
	if !ok {
		return fmt.Errorf("tmclient: cannot find tablet %v", tablet.Alias.Uid)
	}
	t.tm.Ping(ctx, "payload")
	return nil
}

func (itmc *internalTabletManagerClient) GetSchema(
	ctx context.Context,
	tablet *topodatapb.Tablet,
	request *tabletmanagerdatapb.GetSchemaRequest,
) (*tabletmanagerdatapb.SchemaDefinition, error) {
	t, ok := tabletMap[tablet.Alias.Uid]
	if !ok {
		return nil, fmt.Errorf("tmclient: cannot find tablet %v", tablet.Alias.Uid)
	}
	return t.tm.GetSchema(ctx, request)
}

func (itmc *internalTabletManagerClient) GetPermissions(ctx context.Context, tablet *topodatapb.Tablet) (*tabletmanagerdatapb.Permissions, error) {

View on GitHub (pinned to 01a25a7d17)

Solutions

Confirm the tablet UID exists in this vtcombo (check InitTabletMap output / log lines listing created tablets).
Use the correct tablet alias — re-fetch the tablet list from topo rather than caching it.
Refresh/rebuild topo data if it references removed tablets (RebuildKeyspaceGraph, prune stale tablets).
Restart vtcombo with the expected number of tablets if the setup changed.

Example fix

// before: cached alias
oldAlias := "100"
tmclient.Ping(ctx, tabletFromCache)
// after: fetch current tablet from topo
ts, _ := topo.OpenServer(...)
ts.GetTablet(ctx, alias) // errors clearly if tablet is gone

Defensive patterns

Strategy: type-guard

Validate before calling

// resolve the tablet from topo and check it exists before pinging
ti, err := ts.GetTablet(ctx, alias)
if err != nil {
	return fmt.Errorf("tablet %s not in topo: %w", topoproto.TabletAliasString(alias), err)
}
_ = ti

Type guard

func tabletInMap(uid uint32) bool {
	mu.Lock()
	defer mu.Unlock()
	_, ok := tabletMap[uid]
	return ok
}

Try / catch

err := tmClient.Ping(ctx, tablet)
if err != nil && strings.Contains(err.Error(), "tmclient: cannot find tablet") {
	// refresh tablet list from topo and retry with a live alias
}

Prevention

Always fetch tablet aliases from topo immediately before management RPCs
Never cache tablet aliases across vtcombo restarts
Verify tablet UIDs against InitTabletMap startup logs
Clean stale tablets from topo after shard teardown

When it happens

Trigger: Calling any management RPC that pings a tablet (health checks, vtctldclient Ping) with a tablet alias not present in the current vtcombo's tabletMap — e.g. referencing a tablet from another cell/keyspace that was removed, or using a stale alias after vtcombo restart.

Common situations: Stale topology data pointing at tablets removed from vtcombo; running a vttest shard teardown then issuing commands to the old tablet aliases; typo in the tablet UID/alias; vtcombo restarted with fewer tablets than topo references.

Related errors

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