What causes "TableGC: error while reading tables: %+v" in vitessio/vitess?

Inspect the wrapped error for the root cause; most cases are transient — TableGC retries on the next cycle

TableGC: error while reading tables: %+v

Error message

TableGC: error while reading tables: %+v

What it means

TableGC's readAndCheckTables step periodically queries INFORMATION_SCHEMA (or the equivalent) to list tables eligible for GC via readTables. If that read fails (query error, context cancellation, tablet shutdown), the error is wrapped with the 'TableGC:' prefix and propagated up through operate.

Source

Thrown at go/vt/vttablet/tabletserver/gc/tablegc.go:448

// readAndCheckTables is the routine check for which GC tables exist, and which of those need to transition
// into the next state. The function is non-reentrant, and poses a minimal duration between any two executions.
func (collector *TableGC) readAndCheckTables(
	ctx context.Context,
	dropTablesChan chan<- *gcTable,
	transitionRequestsChan chan<- *transitionRequest,
) (err error) {
	if !collector.readReentranceFlag.CompareAndSwap(0, 1) {
		// An instance of this function is already running
		return nil
	}
	defer time.AfterFunc(checkTablesReentryMinInterval, func() {
		collector.readReentranceFlag.Store(0)
	})

	log.Info("TableGC: readAndCheckTables")
	gcTables, err := collector.readTables(ctx)
	if err != nil {
		return fmt.Errorf("TableGC: error while reading tables: %+v", err)
	}
	if err := collector.checkTables(ctx, gcTables, dropTablesChan, transitionRequestsChan); err != nil {
		return err
	}
	return nil
}

// readTables reads the list of _vt_% tables from the database
func (collector *TableGC) readTables(ctx context.Context) (gcTables []*gcTable, err error) {
	conn, err := collector.pool.Get(ctx, nil)
	if err != nil {
		return nil, err
	}
	defer conn.Recycle()

	res, err := conn.Conn.Exec(ctx, sqlShowVtTables, -1, true)
	if err != nil {
		return nil, err

View on GitHub (pinned to 01a25a7d17)

Solutions

Inspect the wrapped error for the root cause; most cases are transient — TableGC retries on the next cycle
Verify MySQL connectivity and DBA credentials used by the GC pool
If caused by shutdown/cancellation, no action needed; ensure graceful tablet drain
Check INFORMATION_SCHEMA availability/performance on the underlying MySQL

Defensive patterns

Strategy: try-catch

Try / catch

// operate loop already retries; on the caller side:
if err := collector.readAndCheckTables(ctx); err != nil {
    log.Warn("TableGC cycle skipped", slog.Any("error", err))
    // rely on next cycle / verify MySQL health
}

Prevention

Ensure stable MySQL connectivity and DBA credentials
Give the GC loop a generous context timeout
Watch tablet shutdown ordering so GC isn't mid-query during drain

When it happens

Trigger: readTables' schema query fails: MySQL/tablet error, ctx cancelled or timed out, database connection dropped while TableGC's operate loop is running.

Common situations: Tablet shutting down while the GC loop fires; network blips between vttablet and MySQL; long-running INFORMATION_SCHEMA queries timing out under load; permission issues with the DBA credentials.

Related errors

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