googleapis/mcp-toolbox · error

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

After constructing the client, Initialize pings the FalkorDB (Redis-compatible) connection; if PING fails, the client is closed and this error is returned with the underlying cause wrapped. The client object was created but no live connection could be established.

Source

Thrown at internal/sources/falkordb/falkordb.go:100

		return nil, err
	}

	logger, err := util.LoggerFromContext(ctx)
	if err != nil {
		return nil, fmt.Errorf("unable to get logger from ctx: %s", err)
	}
	if r.TLS.InsecureSkipVerify {
		logger.WarnContext(ctx, fmt.Sprintf("TLS certificate verification is skipped (insecureSkipVerify: true) for FalkorDB source %s. This exposes traffic for this source to man-in-the-middle attacks. Do not use in production.", r.Name))
	}

	client, err := initFalkorDBClient(ctx, tracer, r)
	if err != nil {
		return nil, fmt.Errorf("unable to create client: %w", err)
	}

	if err := client.Conn.Ping(ctx).Err(); err != nil {
		client.Conn.Close()
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Client: client,
	}
	return s, nil
}

func initFalkorDBClient(ctx context.Context, tracer trace.Tracer, r Config) (*falkordb.FalkorDB, error) {
	//nolint:all // Reassigned ctx
	ctx, span := sources.InitConnectionSpan(ctx, tracer, SourceType, r.Name)
	defer span.End()

	opts := &falkordb.ConnectionOption{
		Addr:     net.JoinHostPort(r.Host, r.Port),
		Username: r.Username,
		Password: r.Password,

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Confirm the server is up and reachable: `redis-cli -h <host> -p <port> PING`
2. Check username/password match the server's auth requirements
3. Match tls.enabled to the server (enable only if the server actually speaks TLS)
4. Inspect the wrapped error: connection refused vs NOAUTH vs TLS handshake tells you which fix applies

Example fix

// before
    tls:
      enabled: true   # server has no TLS
// after
    tls:
      enabled: false

// preflight: server must accept a PING before toolbox startup
redis-cli -u redis://:"$FALKOR_PASS"@"$FALKOR_HOST":"$FALKOR_PORT" PING

// Go: distinguish auth/TLS errors (no retry) from transient connectivity (retry)
src, err := cfg.Initialize(ctx, tracer)
if err != nil && strings.Contains(err.Error(), "unable to connect successfully") {
    if strings.Contains(err.Error(), "WRONGPASS") || strings.Contains(err.Error(), "tls") {
        return err // fix credentials or tls.enabled; retrying won't help
    }
    return retryWithBackoff(ctx, func() error { _, err := cfg.Initialize(ctx, tracer); return err })
}

When it happens

Trigger: Server unreachable at host:port (connection refused/timeout), wrong credentials (Redis NOAUTH/WRONGPASS), TLS handshake failure against a plaintext server or vice versa, or the instance not yet ready.

Common situations: FalkorDB container not started or wrong port; password set via requirepass but missing in config; enabling tls.enabled against a server without TLS (or the reverse); startup ordering in Kubernetes before the DB is ready.

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

• unable to connect successfully: %w
• unable to connect successfully: %w
• toolbox failed to start listener: %w
• unable to connect successfully: %w
• tls.insecureSkipVerify is set on source %q but tls.enabled i

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