cannot create local vtctldclient without a server; call SetS

Error message

cannot create local vtctldclient without a server; call SetServer first

What it means

localVtctldClientFactory builds an in-process vtctld client wired directly to a registered VtctldServer. Because there is no gRPC connection to dial (the addr argument is ignored), the factory fails if no server was previously installed via SetServer, preventing a silently useless client.

Source

Thrown at go/vt/vtctl/localvtctldclient/client.go:67

}

// SetServer sets the server implementation used when creating local clients
// via the vtctldclient.Factory.
//
// This function must be called before calling vtctldclient.New.
func SetServer(s vtctlservicepb.VtctldServer) {
	m.Lock()
	defer m.Unlock()

	server = s
}

func localVtctldClientFactory(ctx context.Context, addr string) (vtctldclient.VtctldClient, error) {
	m.Lock()
	defer m.Unlock()

	if server == nil {
		return nil, errors.New("cannot create local vtctldclient without a server; call SetServer first")
	}

	return New(server), nil
}

func init() {
	vtctldclient.Register("local", localVtctldClientFactory)
}

View on GitHub (pinned to 01a25a7d17)

Solutions

Call localvtctldclient.SetServer(vtctldServer) before any code creates the local client
Fix initialization order so server registration happens in a setup step (or init/TestMain) prior to client creation
If a real vtctld is intended, use the gRPC scheme with a proper vtctld address instead of the local scheme

Example fix

// before
client, err := vtctldclient.New("local")
// after
localvtctldclient.SetServer(fakeVtctldServer)
client, err := vtctldclient.New("local")

Defensive patterns

Strategy: validation

Validate before calling

if localvtctldclient.Server() == nil {
    localvtctldclient.SetServer(vtctldSrv)
}
client, err := vtctldclient.New("local")

Prevention

Register the server in TestMain or a shared setup helper before any client creation
Centralize local client construction in one helper that guarantees SetServer was called
Use the gRPC scheme with a real address outside of tests

When it happens

Trigger: Creating a vtctldclient with the 'local' protocol scheme before test/setup code has called localvtctldclient.SetServer(server).

Common situations: Unit tests constructing a local client before spinning up the fake/mock VtctldServer; initialization-order bugs where the client factory runs before test fixtures register the server.

Related errors

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