vitessio/vitess · error

ForgetInstance(): empty tabletAlias

Error message

ForgetInstance(): empty tabletAlias

What it means

ForgetInstance validates that a non-nil tablet alias was supplied before removing the tablet entry from the vtorc database. A nil alias identifies nothing, so the operation is rejected with this error. It is also logged via log.Error.

Solutions

1. Fix the upstream code path that produced the nil alias.
2. Add a nil check before calling ForgetInstance and skip/log instead.
3. If a tablet should be forgotten, obtain its alias from the topo server (topoproto.TabletAliasString for display) and pass the real alias.

Example fix

// before
err := inst.ForgetInstance(alias) // alias may be nil
// after
if alias != nil {
    err := inst.ForgetInstance(alias)
}

if alias == nil {
    return errors.New("ForgetInstance requires a non-nil tablet alias")
}

func forgettable(a *topodatapb.TabletAlias) bool {
    return a != nil && a.Cell != "" && a.Uid != 0
}

err := inst.ForgetInstance(alias)
if err != nil && strings.Contains(err.Error(), "empty tabletAlias") {
    log.Warn("forget skipped: nil alias")
}

When it happens

Trigger: Calling ForgetInstance(nil) — directly or from refreshTablets — when the alias came from a failed topo read or an unset variable.

Common situations: refreshTablets enumerating tablets when the topo server intermittently returns nil aliases; cleanup scripts calling ForgetInstance with a variable that was never populated.

Related errors

• ReadTopologyInstance will not act on empty tablet alias
• tablet alias is nil
• can't lock shard: keyspace is unspecified
• ForgetInstance(): tablet %+v not found
• aborting , primary mitigation is required

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

Appendix: source

Thrown at go/vt/vtorc/inst/instance_dao.go:1152

	}
	return ExecDBWriteFunc(writeFunc)
}

// InstanceIsForgotten returns true if an instance was forgotten.
func InstanceIsForgotten(tabletAlias *topodatapb.TabletAlias) bool {
	initForgetAliasesCache()
	tabletAliasString := topoproto.TabletAliasString(tabletAlias)
	_, found := forgetAliases.Get(tabletAliasString)
	return found
}

// ForgetInstance removes an instance entry from the vtorc backed database.
// It may be auto-rediscovered through topology or requested for discovery by multiple means.
func ForgetInstance(tabletAlias *topodatapb.TabletAlias) error {
	if tabletAlias == nil {
		errMsg := "ForgetInstance(): empty tabletAlias"
		log.Error(errMsg)
		return errors.New(errMsg)
	}
	initForgetAliasesCache()
	tabletAliasString := topoproto.TabletAliasString(tabletAlias)
	forgetAliases.Set(tabletAliasString, true, cache.DefaultExpiration)
	log.Info(fmt.Sprintf("Forgetting: %v", tabletAliasString))

	// Remove this tablet from errant GTID count metric.
	currentErrantGTIDCount.Reset(tabletAliasString)

	// Drop any shard-peer health reports from this tablet so a deleted observer
	// stops counting toward the quorum denominator immediately.
	RemoveShardPeerObserver(tabletAliasString)

	// Delete from the 'vitess_tablet' table.
	_, err := db.ExecVTOrc(`DELETE FROM
			vitess_tablet
		WHERE
			alias = ?`,

View on GitHub (pinned to 01a25a7d17)