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.

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)

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.