flagutil: NewOptionalFlag requires a non-nil parse function

Error message

flagutil: NewOptionalFlag requires a non-nil parse function

What it means

Cluster.GetVSchemas takes a single topoReadPool slot for the whole multi-cell GetSrvVSchemas call. If acquisition fails (ctx cancelled/timed out waiting), the entire cluster vschema fetch fails with this wrapped error naming the cluster and requested cells.

Solutions

Retry the request
Increase the topo read pool capacity or reduce concurrent callers
Check topo server health/latency (etcd/zk) that lengthens slot hold times

Defensive patterns

Strategy: retry

Try / catch

vs, err := cluster.GetVSchemas(ctx, cells)
if err != nil {
	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
		// wait and retry once with a fresh context
	}
}

Prevention

Limit concurrent cluster-wide vschema fetches
Raise topoReadPool size for large clusters
Track pool wait times via tracing spans

When it happens

Trigger: Calling Cluster.GetVSchemas when the pool has no free slot and the request context is cancelled before Acquire succeeds.

Common situations: Bursts of vschema requests in the vtadmin UI; saturated topoReadPool from parallel fan-out calls; slow topo backends.

Related errors

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

Appendix: source

Thrown at go/flagutil/optional.go:112

func (o *OptionalString) Type() string { return "string" }

func (o *OptionalString) IsSet() bool { return o.set }

// Get returns the underlying string value.
func (o *OptionalString) Get() string { return o.val }

var (
	_ OptionalFlag = (*OptionalFloat64)(nil)
	_ OptionalFlag = (*OptionalString)(nil)
)

// NewOptionalFlag returns a *OptionalFlagValue[T] with the given default value,
// pflag type name, parse function, and stringer.
// It returns an error if parse is nil, since a flag without a parse function cannot be set.
func NewOptionalFlag[T any](defaultVal T, typeName string, parse func(string) (T, error), stringer func(T) string) (*OptionalFlagValue[T], error) {
	if parse == nil {
		return nil, errors.New("flagutil: NewOptionalFlag requires a non-nil parse function")
	}
	return &OptionalFlagValue[T]{
		val:      defaultVal,
		typeName: typeName,
		parse:    parse,
		stringer: stringer,
	}, nil
}

func (f *OptionalFlagValue[T]) Set(arg string) error {
	if f.parse == nil {
		return errors.New("flagutil: OptionalFlagValue has no parse function; use a constructor such as NewOptionalFlag")
	}

	v, err := f.parse(arg)
	if err != nil {
		return err
	}

View on GitHub (pinned to 01a25a7d17)