vitessio/vitess · warning

ForgetInstance(): tablet %+v not found

Error message

ForgetInstance(): tablet %+v not found

What it means

ForgetInstance deletes the tablet row from the vtorc database; when the DELETE affects zero rows, the tablet does not exist and this error is returned. It confirms the requested tablet alias was already forgotten or never discovered.

Solutions

1. Treat it as benign if the goal is 'tablet must not be tracked' — check and ignore, or use a helper that tolerates not-found.
2. Verify the alias (cell + uid) is correct with topoproto.TabletAliasString.
3. Query the vtorc database_instance table first to confirm the tablet is present before forgetting.

Example fix

// before
if err := inst.ForgetInstance(alias); err != nil { return err }
// after
if err := inst.ForgetInstance(alias); err != nil && !strings.Contains(err.Error(), "not found") {
    return err
}

exists, err := instanceExistsInDb(alias)
if err == nil && !exists {
    return nil // already forgotten
}

err := inst.ForgetInstance(alias)
if err != nil && strings.Contains(err.Error(), "not found") {
    return nil // idempotent: nothing to forget
} else if err != nil { return err }

When it happens

Trigger: Calling ForgetInstance with an alias that has no row in the vtorc database — e.g., forgetting twice, or forgetting a tablet vtorc never discovered.

Common situations: Double invocation of forget in recovery scripts; racing with refreshTablets which already pruned the stale tablet; typo in cell/uid components of the alias.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• ForgetInstance(): empty tabletAlias
• keyspace not found
• shard not found
• aborting , primary mitigation is required
• API registered but not handled. Please open an issue at…

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

Appendix: source

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

			database_instance
		WHERE
			alias = ?`,
		tabletAliasString,
	)
	if err != nil {
		log.Error(err.Error())
		return err
	}
	// Get the number of rows affected. If they are zero, then we tried to forget an instance that doesn't exist.
	rows, err := sqlResult.RowsAffected()
	if err != nil {
		log.Error(err.Error())
		return err
	}
	if rows == 0 {
		errMsg := fmt.Sprintf("ForgetInstance(): tablet %+v not found", tabletAliasString)
		log.Error(errMsg)
		return errors.New(errMsg)
	}
	_ = AuditOperation("forget", tabletAlias, "")
	return nil
}

// ForgetLongUnseenInstances will remove entries of all instances that have long since been last seen.
func ForgetLongUnseenInstances() error {
	sqlResult, err := db.ExecVTOrc(`DELETE
		FROM database_instance
		WHERE
			last_seen < DATETIME('now', PRINTF('-%d HOUR', ?))
		`,
		config.UnseenInstanceForgetHours,
	)
	if err != nil {
		log.Error(err.Error())
		return err
	}

View on GitHub (pinned to 01a25a7d17)