{"record":{"id":"9953a7997da7ed58","repo":"googleapis/mcp-toolbox","slug":"error-initializing-valkey-client-s","errorCode":null,"errorMessage":"error initializing Valkey client: %s","messagePattern":"error initializing Valkey client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/valkey/valkey.go","lineNumber":65,"sourceCode":"\tName         string   `yaml:\"name\" validate:\"required\"`\n\tType         string   `yaml:\"type\" validate:\"required\"`\n\tAddress      []string `yaml:\"address\" validate:\"required\"`\n\tUsername     string   `yaml:\"username\"`\n\tPassword     string   `yaml:\"password\"`\n\tDatabase     int      `yaml:\"database\"`\n\tUseGCPIAM    bool     `yaml:\"useGCPIAM\"`\n\tDisableCache bool     `yaml:\"disableCache\"`\n}\n\nfunc (r Config) SourceConfigType() string {\n\treturn SourceType\n}\n\nfunc (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {\n\n\tclient, err := initValkeyClient(ctx, r)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error initializing Valkey client: %s\", err)\n\t}\n\ts := &Source{\n\t\tConfig: r,\n\t\tClient: client,\n\t}\n\treturn s, nil\n}\n\nfunc initValkeyClient(ctx context.Context, r Config) (valkey.Client, error) {\n\tvar authFn func(valkey.AuthCredentialsContext) (valkey.AuthCredentials, error)\n\tif r.UseGCPIAM {\n\t\t// Pass in an access token getter fn for IAM auth\n\t\tauthFn = func(valkey.AuthCredentialsContext) (valkey.AuthCredentials, error) {\n\t\t\ttoken, err := sources.GetIAMAccessToken(ctx)\n\t\t\tcreds := valkey.AuthCredentials{Username: \"default\", Password: token}\n\t\t\tif err != nil {\n\t\t\t\treturn creds, err\n\t\t\t}","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/valkey/valkey.go#L47-L83","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the address/host/port in the source config is correct and reachable (e.g. 'redis-cli -h <host> -p <port> ping')","Ensure the Valkey/Redis server is running and reachable from the toolbox process (Docker network, firewall)","Check TLS/credential settings on the source config match the server's requirements","Read the wrapped '%s' cause in the message for the specific underlying failure"],"exampleFix":"// before\nsources:\n  valkey:\n    kind: valkey\n    address: localhst:6379\n// after\nsources:\n  valkey:\n    kind: valkey\n    address: localhost:6379","handlingStrategy":"validation","validationCode":"// Before starting the toolbox, verify the Valkey address is reachable\nconst [host, port] = address.split(\":\");\nconst net = require(\"net\");\nconst s = net.createConnection({ host, port: Number(port) });\ns.on(\"connect\", () => { console.log(\"valkey reachable\"); s.end(); });\ns.on(\"error\", (e) => { throw new Error(`Cannot reach ${address}: ${e.message}`); });","typeGuard":"function isValidAddress(addr: string): boolean {\n  return /^[a-zA-Z0-9._-]+:\\d{1,5}$/.test(addr);\n}","tryCatchPattern":"try {\n  await startToolbox();\n} catch (err) {\n  if (String(err).includes(\"error initializing Valkey client\")) {\n    console.error(\"Check valkey address/server: \", err.message);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Test the address with redis-cli/valkey-cli ping before wiring it into tools.yaml","Ensure containers share a Docker network or the host is reachable from the toolbox","Pin addresses via environment variables to avoid environment-specific typos","Match TLS/auth settings to the server's configuration"],"tags":["valkey","redis","connection","initialization"],"backgroundTag":"client-initialization-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}