{"record":{"id":"8185c5e1e1446d68","repo":"vitessio/vitess","slug":"readtopologyinstance-v-v","errorCode":null,"errorMessage":"ReadTopologyInstance(%+v): %+v","messagePattern":"ReadTopologyInstance\\(%\\+v\\): %\\+v","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"go/vt/vtorc/inst/instance_dao.go","lineNumber":148,"sourceCode":"func logReadTopologyInstanceError(tabletAlias *topodatapb.TabletAlias, hint string, err error) error {\n\tif err == nil {\n\t\treturn nil\n\t}\n\ttabletAliasString := topoproto.TabletAliasString(tabletAlias)\n\tif !util.ClearToLog(\"ReadTopologyInstance\", tabletAliasString) {\n\t\treturn err\n\t}\n\tvar msg string\n\tif hint == \"\" {\n\t\tmsg = fmt.Sprintf(\"ReadTopologyInstance(%+v): %+v\", tabletAliasString, err)\n\t} else {\n\t\tmsg = fmt.Sprintf(\"ReadTopologyInstance(%+v) %+v: %+v\",\n\t\t\ttabletAliasString,\n\t\t\tstrings.ReplaceAll(hint, \"%\", \"%%\"), // escape %\n\t\t\terr)\n\t}\n\tlog.Error(msg)\n\treturn errors.New(msg)\n}\n\n// RegisterStats registers stats from the inst package\nfunc RegisterStats() {\n\tstats.NewGaugeFunc(\"ErrantGtidTabletCount\", \"Number of tablets with errant GTIDs\", func() int64 {\n\t\tinstances, _ := ReadInstancesWithErrantGTIds(\"\", \"\")\n\t\treturn int64(len(instances))\n\t})\n}\n\n// ReadTopologyInstanceBufferable connects to a topology MySQL instance\n// and collects information on the server and its replication state.\n// It writes the information retrieved into vtorc's backend.\n// - writes are optionally buffered.\n// - timing information can be collected for the stages performed.\nfunc ReadTopologyInstanceBufferable(tabletAlias *topodatapb.TabletAlias, latency *stopwatch.NamedStopwatch) (inst *Instance, err error) {\n\tdefer func() {\n\t\tif r := recover(); r != nil {","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtorc/inst/instance_dao.go#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the underlying cause in the wrapped error and verify the tablet process is up (vttablet logs, ps/netstat).","Verify network connectivity and ports between vtorc and the tablet host.","Confirm MySQL credentials configured for vtorc are valid on the tablet's backend.","If the tablet is intentionally gone, run ForgetInstance or let refreshTablets prune it."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if alias == nil {\n    return errors.New(\"no tablet alias to read topology for\")\n}\nif err := pingTabletHost(alias); err != nil {\n    return fmt.Errorf(\"tablet unreachable before discovery: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"inst, err := inst.ReadTopologyInstanceBufferable(ctx, alias, hint)\nif err != nil {\n    log.Warn(\"topology read failed; will retry on next tick\", slog.Any(\"error\", err))\n    return nil // vtorc retries discovery periodically\n}","preventionTips":["Monitor tablet health and connectivity proactively so failures are caught before discovery.","Keep vtorc MySQL credentials current and rotated consistently across cells.","Alert on repeated ReadTopologyInstance failures for the same tablet alias.","Forget stale tablets so vtorc does not keep probing dead hosts."],"tags":["vtorc","topology-discovery","tablet","mysql"],"backgroundTag":"topology-discovery-failure","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}