googleapis/mcp-toolbox · error

error initializing Valkey client: %s

Error message

error initializing Valkey client: %s

What it means

The Valkey source's Config.Initialize calls initValkeyClient to construct a valkey-go client from the configured address/credentials. Any failure creating that client (bad address, connection refused, invalid settings) is wrapped as 'error initializing Valkey client: %s'. It indicates the Valkey source could not be created and the toolbox cannot start this source.

Source

Thrown at internal/sources/valkey/valkey.go:65

	Name         string   `yaml:"name" validate:"required"`
	Type         string   `yaml:"type" validate:"required"`
	Address      []string `yaml:"address" validate:"required"`
	Username     string   `yaml:"username"`
	Password     string   `yaml:"password"`
	Database     int      `yaml:"database"`
	UseGCPIAM    bool     `yaml:"useGCPIAM"`
	DisableCache bool     `yaml:"disableCache"`
}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {

	client, err := initValkeyClient(ctx, r)
	if err != nil {
		return nil, fmt.Errorf("error initializing Valkey client: %s", err)
	}
	s := &Source{
		Config: r,
		Client: client,
	}
	return s, nil
}

func initValkeyClient(ctx context.Context, r Config) (valkey.Client, error) {
	var authFn func(valkey.AuthCredentialsContext) (valkey.AuthCredentials, error)
	if r.UseGCPIAM {
		// Pass in an access token getter fn for IAM auth
		authFn = func(valkey.AuthCredentialsContext) (valkey.AuthCredentials, error) {
			token, err := sources.GetIAMAccessToken(ctx)
			creds := valkey.AuthCredentials{Username: "default", Password: token}
			if err != nil {
				return creds, err
			}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the address/host/port in the source config is correct and reachable (e.g. 'redis-cli -h <host> -p <port> ping')
2. Ensure the Valkey/Redis server is running and reachable from the toolbox process (Docker network, firewall)
3. Check TLS/credential settings on the source config match the server's requirements
4. Read the wrapped '%s' cause in the message for the specific underlying failure

Example fix

// before
sources:
  valkey:
    kind: valkey
    address: localhst:6379
// after
sources:
  valkey:
    kind: valkey
    address: localhost:6379

// Before starting the toolbox, verify the Valkey address is reachable
const [host, port] = address.split(":");
const net = require("net");
const s = net.createConnection({ host, port: Number(port) });
s.on("connect", () => { console.log("valkey reachable"); s.end(); });
s.on("error", (e) => { throw new Error(`Cannot reach ${address}: ${e.message}`); });

function isValidAddress(addr: string): boolean {
  return /^[a-zA-Z0-9._-]+:\d{1,5}$/.test(addr);
}

try {
  await startToolbox();
} catch (err) {
  if (String(err).includes("error initializing Valkey client")) {
    console.error("Check valkey address/server: ", err.message);
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Config.Initialize with an unreachable or malformed Valkey/Redis address (e.g. wrong host/port, 'localhost:0000'), DNS failure, or client rejected settings (invalid TLS/credentials options) during source initialization at server startup.

Common situations: Typo in address in the tools.yaml config; Valkey server not running or in another container/network; firewall blocking the port; using a Redis URL format valkey-go does not accept.

Related errors

• unable to create session: %v
• unable to create db connection: %w
• unable to initialize source %q: %w
• unable to connect to redis cluster: %s
• unable to connect to redis: %s

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/9953a7997da7ed58. Report an issue: GitHub.