vitessio/vitess · warning

ReadTopologyInstance(%+v): %+v

Error message

ReadTopologyInstance(%+v): %+v

What it means

VTOrc's ReadTopologyInstance failed to read a tablet's topology information and this error wraps the underlying cause. It is logged via logReadTopologyInstanceError and returned so callers (like ReadTopologyInstanceBufferable) know discovery of that tablet failed. The hint and tablet alias are embedded in the message to identify which tablet and which phase of reading failed.

Source

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

func logReadTopologyInstanceError(tabletAlias *topodatapb.TabletAlias, hint string, err error) error {
	if err == nil {
		return nil
	}
	tabletAliasString := topoproto.TabletAliasString(tabletAlias)
	if !util.ClearToLog("ReadTopologyInstance", tabletAliasString) {
		return err
	}
	var msg string
	if hint == "" {
		msg = fmt.Sprintf("ReadTopologyInstance(%+v): %+v", tabletAliasString, err)
	} else {
		msg = fmt.Sprintf("ReadTopologyInstance(%+v) %+v: %+v",
			tabletAliasString,
			strings.ReplaceAll(hint, "%", "%%"), // escape %
			err)
	}
	log.Error(msg)
	return errors.New(msg)
}

// RegisterStats registers stats from the inst package
func RegisterStats() {
	stats.NewGaugeFunc("ErrantGtidTabletCount", "Number of tablets with errant GTIDs", func() int64 {
		instances, _ := ReadInstancesWithErrantGTIds("", "")
		return int64(len(instances))
	})
}

// ReadTopologyInstanceBufferable connects to a topology MySQL instance
// and collects information on the server and its replication state.
// It writes the information retrieved into vtorc's backend.
// - writes are optionally buffered.
// - timing information can be collected for the stages performed.
func ReadTopologyInstanceBufferable(tabletAlias *topodatapb.TabletAlias, latency *stopwatch.NamedStopwatch) (inst *Instance, err error) {
	defer func() {
		if r := recover(); r != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the underlying cause in the wrapped error and verify the tablet process is up (vttablet logs, ps/netstat).
2. Verify network connectivity and ports between vtorc and the tablet host.
3. Confirm MySQL credentials configured for vtorc are valid on the tablet's backend.
4. If the tablet is intentionally gone, run ForgetInstance or let refreshTablets prune it.

if alias == nil {
    return errors.New("no tablet alias to read topology for")
}
if err := pingTabletHost(alias); err != nil {
    return fmt.Errorf("tablet unreachable before discovery: %w", err)
}

inst, err := inst.ReadTopologyInstanceBufferable(ctx, alias, hint)
if err != nil {
    log.Warn("topology read failed; will retry on next tick", slog.Any("error", err))
    return nil // vtorc retries discovery periodically
}

When it happens

Trigger: Any failure during ReadTopologyInstance tablet discovery: MySQL connection failures to the tablet's backend, tablet RPC errors fetching replication status, or timeouts while probing the tablet.

Common situations: A tablet is down or being restarted; network partition between vtorc and the tablet; MySQL credentials for vtorc are wrong; the tablet alias resolves to an unreachable host after a reparent or cell decommission.

Related errors

• ReadTopologyInstance will not act on empty tablet alias
• tablet alias is nil
• recovery.IsRecoveryDisabled(): %v
• no client certs for connection
• unexpected: query ended without no results and no error

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