What causes "unable to connect to redis: %s" in googleapis/mcp-toolbox?

Test connectivity manually: `redis-cli -h -p ping` from the machine running the toolbox.

unable to connect to redis: %s

Error message

unable to connect to redis: %s

What it means

This error wraps the failure from a standalone (non-cluster) go-redis client Ping during source initialization. After building redis.UniversalClient with the configured address, username, password, and TLS settings, the toolbox pings the server; any failure (network, auth, TLS) aborts source creation. The wrapped message carries the specific cause.

Source

Thrown at internal/sources/redis/redis.go:147

		client = clusterClient
		return client, nil
	}

	// Create a new Redis client
	standaloneClient := redis.NewClient(&redis.Options{
		Addr:                       r.Address[0],
		PoolSize:                   10,
		ConnMaxIdleTime:            60 * time.Second,
		MinIdleConns:               1,
		DB:                         r.Database,
		CredentialsProviderContext: authFn,
		Username:                   r.Username,
		Password:                   r.Password,
		TLSConfig:                  tlsConfig,
	})
	_, err = standaloneClient.Ping(ctx).Result()
	if err != nil {
		return nil, fmt.Errorf("unable to connect to redis: %s", err)
	}
	client = standaloneClient
	return client, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Client RedisClient
}

func (s *Source) IsReadOnly() bool {
	return false
}

func (s *Source) SourceType() string {
	return SourceType

View on GitHub (pinned to 8cc6e09de2)

Solutions

Test connectivity manually: `redis-cli -h <host> -p <port> ping` from the machine running the toolbox.
Confirm `password`/`username` match Redis `requirepass` or ACL user; WRONGPASS means credentials are wrong.
Match TLS settings to the server: remove TLS config for plaintext servers, add server CA for TLS-enabled servers.
Check the address scheme — the address must include the port and be reachable (no typos like 6379 vs 7379).
If Redis is still starting (LOADING), add retry/backoff or wait for the instance to be ready.

Example fix

// before
sources:
  my-redis:
    kind: redis
    address: localhost:6379
    useServerCA: true
// after (plaintext local redis, no TLS)
sources:
  my-redis:
    kind: redis
    address: localhost:6379

Defensive patterns

Strategy: validation

Validate before calling

// Verify the standalone Redis instance before starting the toolbox
redis-cli -h "${REDIS_HOST:-localhost}" -p "${REDIS_PORT:-6379}" \
  $( [ -n "$REDIS_PASSWORD" ] && echo "-a $REDIS_PASSWORD" ) ping
echo $REDIS_ADDRESS # must be host:port, e.g. localhost:6379

Prevention

Always smoke-test the address with redis-cli ping from the toolbox host first.
Match TLS config exactly to the server mode; wrong TLS settings cause opaque ping failures.
For Redis 6+ ACL, set both username and password; for requirepass-only, password alone suffices.
Handle LOADING at startup: wait for the instance to be ready before launching the toolbox.

When it happens

Trigger: Redis source with clusterMode=false (default); Initialize calls standaloneClient.Ping(ctx) which fails because the server is down, address is wrong, credentials are invalid, or TLS settings mismatch.

Common situations: Redis not running or wrong `address` port; missing/incorrect `password` (NOAUTH/WRONGPASS errors); using TLS config against a plaintext server or vice versa; Redis behind VPC/Security Group blocking the toolbox host; Redis currently loading RDB (LOADING error).

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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