dgraph-io/dgraph · error

error opening connection with Dgraph Alpha: %v

Error message

error opening connection with Dgraph Alpha: %v

What it means

The MCP server's getConn helper failed to establish a gRPC connection to a Dgraph Alpha via dgo.Open after retrying over the configured endpoints. The underlying dial error is embedded in the message. Without a connection, no MCP tool or resource can serve requests.

Source

Thrown at dgraph/cmd/mcp/mcp_server.go:47

func getConn(connectionString string) (*dgo.Dgraph, error) {
	getConnLock.Lock()
	defer getConnLock.Unlock()

	if dgraphConnection != nil {
		return dgraphConnection, nil
	}

	conn, err := dgo.Open(connectionString)
	if err != nil {
		for i := range 3 {
			time.Sleep(time.Second * time.Duration(i))
			conn, err = dgo.Open(connectionString)
			if err == nil {
				break
			}
		}
		if err != nil {
			return nil, fmt.Errorf("error opening connection with Dgraph Alpha: %v", err)
		}
	}
	dgraphConnection = conn
	return conn, nil
}

var True = true
var False = false

// NewMCPServer initializes and returns a new MCPServer instance.
func NewMCPServer(connectionString string, readOnly bool) (*server.MCPServer, error) {
	s := server.NewMCPServer(
		"Dgraph MCP Server",
		x.Version(),
		server.WithResourceCapabilities(true, true),
		server.WithLogging(),
		server.WithRecovery(),
	)

View on GitHub (pinned to 759e242be6)

Solutions

1. Verify an Alpha is reachable: `grpcurl` or `telnet <host> 9080`, and fix the connection string (use grpc port 9080)
2. Start/restart the Dgraph Alpha before launching the MCP server
3. Fix DNS/container networking (use service hostname instead of localhost inside containers)
4. If TLS is enabled on Alpha, supply the correct TLS options in the connection string

Example fix

// before
dgraphConnectionUrl = "localhost:8080"   // HTTP port
// after
dgraphConnectionUrl = "localhost:9080"   // gRPC port

// Probe the Alpha gRPC port before starting/serving MCP
cimport net from 'net';
function alphaReachable(host, port = 9080, timeout = 3000) {
  return new Promise(resolve => {
    const s = net.connect(port, host);
    s.setTimeout(timeout);
    s.once('connect', () => { s.destroy(); resolve(true); });
    s.once('error', () => resolve(false));
    s.once('timeout', () => { s.destroy(); resolve(false); });
  });
}

function isConnected(conn) {
  return conn != null && typeof conn.NewTxn === 'function';
}

try {
  conn = await getConn(connectionString);
} catch (e) {
  if (String(e.message).includes('error opening connection with Dgraph Alpha')) {
    await backoffRetry(() => getConn(connectionString), 5); // exponential backoff
  } else { throw e; }
}

When it happens

Trigger: DGRAPH_ALPHA or the configured connection string points at an unreachable host/port; no Alpha is running; wrong port (default gRPC 9080, not 8080); DNS failure; TLS mismatch between client and Alpha.

Common situations: MCP server started before the Dgraph cluster is up; container networking misconfiguration (localhost inside a container); using the HTTP port 8080 instead of gRPC 9080; firewall blocking the port.

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

• error opening connection with Dgraph Alpha: %w
• failed to connect to endpoint [%s]: %w
• failed to disable drain mode: %v
• failed to start external snapshot stream for group %d: %w
• failed to send request for group ID [%v] to the server: %w

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/c468b875703a0667. Report an issue: GitHub.