What causes "unable to connect successfully: %w" in googleapis/mcp-toolbox?

Verify the ArcadeDB server is running and listening on the Bolt port: 'nc -vz 2424'.

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

After the driver is created, Initialize calls driver.VerifyConnectivity to perform an actual handshake with the ArcadeDB server. This error means the driver exists but the server could not be reached or rejected the connection — network failure, wrong port, server down, or authentication rejected at handshake. The driver is closed before returning the error.

Source

Thrown at internal/sources/arcadedb/arcadedb.go:89

	HTTPUri    string `yaml:"httpUri"`
	HTTPScheme string `yaml:"httpScheme"`
	HTTPPort   int    `yaml:"httpPort"`
}

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

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	driver, err := initArcadeDBDriver(ctx, tracer, r.Uri, r.User, r.Password, r.Name)
	if err != nil {
		return nil, fmt.Errorf("unable to create driver: %w", err)
	}

	err = driver.VerifyConnectivity(ctx)
	if err != nil {
		driver.Close(ctx)
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Driver: driver,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Driver neo4j.Driver
}

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

Verify the ArcadeDB server is running and listening on the Bolt port: 'nc -vz <host> 2424'.
Confirm the URI uses the Bolt port (2424), not the HTTP API port (2480).
Check username/password against the ArcadeDB server config and test with another Bolt client.
Inspect network/firewall/Docker networking between the toolbox and the database.

Example fix

// before: HTTP port in a Bolt URI
uri: bolt://localhost:2480
// after
uri: bolt://localhost:2424

Defensive patterns

Strategy: try-catch

Validate before calling

host, port := "localhost", 2424
conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, port), 3*time.Second)
if err != nil {
    return fmt.Errorf("ArcadeDB Bolt port unreachable: %w", err)
}
conn.Close()

Try / catch

if err := driver.VerifyConnectivity(ctx); err != nil {
    // server down, wrong port, or bad credentials
    return fmt.Errorf("cannot reach ArcadeDB at %s: %w", uri, err)
}

Prevention

Monitor ArcadeDB server health (TCP check on 2424) before starting dependent services.
Use the correct Bolt port (2424), not the HTTP port (2480).
Verify credentials against the server with a standalone Bolt client.
Check Docker network/firewall rules allow the toolbox host to reach the DB host.

When it happens

Trigger: Calling Initialize when the ArcadeDB host/port is unreachable, the server is not listening, TLS is misconfigured, or credentials are rejected during the Bolt handshake.

Common situations: ArcadeDB container not started; wrong port (2480 HTTP vs 2424 Bolt); firewall or Docker network isolation; wrong username/password; server behind a proxy that does not speak Bolt.

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/44d84dd7286114a1. Report an issue: GitHub.