What causes "ForgetInstance(): empty tabletAlias" in vitessio/vitess?

Fix the upstream code path that produced the nil alias.

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.

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)

Solutions

Fix the upstream code path that produced the nil alias.
Add a nil check before calling ForgetInstance and skip/log instead.
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)
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Validate aliases at the boundary of topo reads before any mutation APIs.
Never propagate nil aliases through cleanup/recovery code paths.

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

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