What causes "unknown mysqlctl client protocol: %v" in vitessio/vitess?

Set --mysqlctl_client_protocol=grpc (lowercase).

unknown mysqlctl client protocol: %v

Error message

unknown mysqlctl client protocol: %v

What it means

mysqlctlclient.New resolves the client implementation from a package-level registry keyed by the `protocol` flag; if the protocol value has no registered factory, this error is returned. Only protocols whose client packages were imported (registered via init) are available.

Source

Thrown at go/vt/mysqlctl/mysqlctlclient/interface.go:93

// Factory functions are registered by client implementations.
type Factory func(ctx context.Context, network, addr string) (MysqlctlClient, error)

var factories = make(map[string]Factory)

// RegisterFactory allows a client implementation to register itself
func RegisterFactory(name string, factory Factory) {
	if _, ok := factories[name]; ok {
		log.Error(fmt.Sprintf("RegisterFactory %s already exists", name))
		os.Exit(1)
	}
	factories[name] = factory
}

// New creates a client implementation as specified by a flag.
func New(ctx context.Context, network, addr string) (MysqlctlClient, error) {
	factory, ok := factories[protocol]
	if !ok {
		return nil, fmt.Errorf("unknown mysqlctl client protocol: %v", protocol)
	}
	return factory(ctx, network, addr)
}

View on GitHub (pinned to 01a25a7d17)

Solutions

Set --mysqlctl_client_protocol=grpc (lowercase).
Ensure the binary imports the grpcmysqlctlclient package (directly or via vitess defaults) so its factory registers.
Check the flag spelling against go/vt/mysqlctl/mysqlctlclient/interface.go registry.

Example fix

// before
--mysqlctl_client_protocol http
// after
--mysqlctl_client_protocol grpc

Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"grpc": true}
if !allowed[flags.GetString("mysqlctl_client_protocol")] {
	return errors.New("mysqlctl_client_protocol must be grpc")
}

Try / catch

client, err := mysqlctlclient.New(ctx, network, addr)
if err != nil {
	if strings.Contains(err.Error(), "unknown mysqlctl client protocol") { /* fix protocol flag */ }
	return err
}

Prevention

Only use the documented protocol value 'grpc' in flags
Keep blank imports of client implementation packages in custom builds
Add flag validation in PreRunE to catch bad protocol values before RPC time

When it happens

Trigger: Calling New with --mysqlctl_client_protocol set to anything other than grpc (the only factory registered by default), or building a binary that does not import the grpcmysqlctlclient package so factories is empty.

Common situations: Typo like 'GRPC' (case-sensitive) or 'grpc2'; custom builds missing the blank import `_ "vitess.io/vitess/go/vt/mysqlctl/grpcmysqlctlclient"`; stale flags copied from another deployment.

Related errors

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