{"record":{"id":"c468b875703a0667","repo":"dgraph-io/dgraph","slug":"error-opening-connection-with-dgraph-alpha-v","errorCode":null,"errorMessage":"error opening connection with Dgraph Alpha: %v","messagePattern":"error opening connection with Dgraph Alpha: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"dgraph/cmd/mcp/mcp_server.go","lineNumber":47,"sourceCode":"func getConn(connectionString string) (*dgo.Dgraph, error) {\n\tgetConnLock.Lock()\n\tdefer getConnLock.Unlock()\n\n\tif dgraphConnection != nil {\n\t\treturn dgraphConnection, nil\n\t}\n\n\tconn, err := dgo.Open(connectionString)\n\tif err != nil {\n\t\tfor i := range 3 {\n\t\t\ttime.Sleep(time.Second * time.Duration(i))\n\t\t\tconn, err = dgo.Open(connectionString)\n\t\t\tif err == nil {\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error opening connection with Dgraph Alpha: %v\", err)\n\t\t}\n\t}\n\tdgraphConnection = conn\n\treturn conn, nil\n}\n\nvar True = true\nvar False = false\n\n// NewMCPServer initializes and returns a new MCPServer instance.\nfunc NewMCPServer(connectionString string, readOnly bool) (*server.MCPServer, error) {\n\ts := server.NewMCPServer(\n\t\t\"Dgraph MCP Server\",\n\t\tx.Version(),\n\t\tserver.WithResourceCapabilities(true, true),\n\t\tserver.WithLogging(),\n\t\tserver.WithRecovery(),\n\t)","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/dgraph/cmd/mcp/mcp_server.go#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify an Alpha is reachable: `grpcurl` or `telnet <host> 9080`, and fix the connection string (use grpc port 9080)","Start/restart the Dgraph Alpha before launching the MCP server","Fix DNS/container networking (use service hostname instead of localhost inside containers)","If TLS is enabled on Alpha, supply the correct TLS options in the connection string"],"exampleFix":"// before\ndgraphConnectionUrl = \"localhost:8080\"   // HTTP port\n// after\ndgraphConnectionUrl = \"localhost:9080\"   // gRPC port","handlingStrategy":"retry","validationCode":"// Probe the Alpha gRPC port before starting/serving MCP\ncimport net from 'net';\nfunction alphaReachable(host, port = 9080, timeout = 3000) {\n  return new Promise(resolve => {\n    const s = net.connect(port, host);\n    s.setTimeout(timeout);\n    s.once('connect', () => { s.destroy(); resolve(true); });\n    s.once('error', () => resolve(false));\n    s.once('timeout', () => { s.destroy(); resolve(false); });\n  });\n}","typeGuard":"function isConnected(conn) {\n  return conn != null && typeof conn.NewTxn === 'function';\n}","tryCatchPattern":"try {\n  conn = await getConn(connectionString);\n} catch (e) {\n  if (String(e.message).includes('error opening connection with Dgraph Alpha')) {\n    await backoffRetry(() => getConn(connectionString), 5); // exponential backoff\n  } else { throw e; }\n}","preventionTips":["Point the connection string at the gRPC port (9080), not HTTP 8080","Add readiness checks so the MCP server starts only after the Alpha is up","Use service DNS names, not localhost, in containerized deployments","Enable TLS settings consistently on both client and Alpha"],"tags":["network","grpc","connection","mcp"],"backgroundTag":"connection-refused","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}