What causes "GetCellsAliases() failed to acquire topoReadPool: %w" in vitessio/vitess?

GetCellsAliases() failed to acquire topoReadPool: %w

Error message

GetCellsAliases() failed to acquire topoReadPool: %w

What it means

GetCellsAliases takes a topoReadPool slot before querying the topology for cell aliases. Acquire failure means the request context ended while waiting for a pool slot, so aliases cannot be fetched and the error is returned to the caller directly (not recorded on a collector).

Source

Thrown at go/vt/vtadmin/cluster/cluster.go:1137

			})
		}(name)
	}

	wg.Wait()
	if rec.HasErrors() {
		return nil, rec.Error()
	}

	return infos, nil
}

// GetCellsAliases returns all CellsAliases in the cluster.
func (c *Cluster) GetCellsAliases(ctx context.Context) (*vtadminpb.ClusterCellsAliases, error) {
	span, ctx := trace.NewSpan(ctx, "Cluster.GetCellsAliases")
	defer span.Finish()

	if err := c.topoReadPool.Acquire(ctx); err != nil {
		return nil, fmt.Errorf("GetCellsAliases() failed to acquire topoReadPool: %w", err)
	}
	defer c.topoReadPool.Release()

	resp, err := c.Vtctld.GetCellsAliases(ctx, &vtctldatapb.GetCellsAliasesRequest{})
	if err != nil {
		return nil, err
	}

	return &vtadminpb.ClusterCellsAliases{
		Cluster: c.ToProto(),
		Aliases: resp.Aliases,
	}, nil
}

// GetGates returns the list of all VTGates in the cluster.
func (c *Cluster) GetGates(ctx context.Context) ([]*vtadminpb.VTGate, error) {
	// (TODO|@ajm188) Support tags in the vtadmin RPC request and pass them
	// through here.

View on GitHub (pinned to 01a25a7d17)

Solutions

Retry with a longer deadline
Increase topoReadPool size in cluster config
Reduce concurrent topology-heavy requests
Check for leaked/stuck Acquire holders (slow vtctld RPCs) and fix the underlying slowness

Example fix

// before
ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
// after: allow enough headroom for pool wait + RPC
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)

Defensive patterns

Strategy: retry

Try / catch

aliases, err := cluster.GetCellsAliases(ctx)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        // pool/timeout pressure: retry with a longer deadline
    }
    return err
}

Prevention

Keep topoReadPool sized to concurrent topo readers
Avoid many simultaneous topology calls per render
Use client deadlines with headroom
Alert on sustained pool saturation

When it happens

Trigger: Calling GetCellsAliases while topoReadPool is exhausted and ctx is canceled/deadlined during c.topoReadPool.Acquire(ctx).

Common situations: Heavy concurrent topo reads (cells, keyspaces, aliases) exhausting the shared pool; short client deadlines; burst dashboard load.

Related errors

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