dgraph-io/dgraph · error

error opening connection with Dgraph Alpha: %w

Error message

error opening connection with Dgraph Alpha: %w

What it means

The dgraph://schema MCP resource handler wraps a getConn failure with this message when it cannot open a connection to the Alpha before running the `schema {}` query. It is the same underlying dial failure as the getConn error, re-wrapped for the resource read path.

Source

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

		resp, err := txn.Query(ctx, "schema {}")
		if err != nil {
			return mcp.NewToolResultErrorFromErr("Error running query", err), nil
		}
		return mcp.NewToolResultText(string(resp.GetJson())), nil
	})

	schemaResource := mcp.NewResource(
		"dgraph://schema",
		"dgraph_schema",
		mcp.WithResourceDescription("The current Dgraph DQL schema"),
		mcp.WithMIMEType("text/plain"),
	)

	s.AddResource(schemaResource, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
		// Execute operation
		conn, err := getConn(connectionString)
		if err != nil {
			return nil, fmt.Errorf("error opening connection with Dgraph Alpha: %w", err)
		}
		resp, err := conn.NewTxn().Query(ctx, "schema {}")
		if err != nil {
			return nil, fmt.Errorf("error running query: %w", err)
		}

		return []mcp.ResourceContents{
			mcp.TextResourceContents{
				URI:      "dgraph://schema",
				MIMEType: "text/plain",
				Text:     string(resp.Json),
			},
		}, nil
	})

	commonQueriesTool := mcp.NewTool("get_common_queries",
		mcp.WithDescription("Get common queries that you can run on the db. If you are seeing issues with your queries, you can check this tool once."),
		mcp.WithToolAnnotation(mcp.ToolAnnotation{

View on GitHub (pinned to 759e242be6)

Solutions

1. Ensure the Dgraph Alpha is running and reachable at the configured gRPC address
2. Correct the connection string/port (9080) in the MCP server configuration
3. Check network/firewall between the MCP server host and the Alpha

Example fix

// before (env)
DGRAPH_ALPHA=alpha:8080
// after
DGRAPH_ALPHA=alpha:9080

// Health-check before reading the schema resource
const health = await fetch('http://alpha:8080/health');
if (!health.ok) throw new Error('Alpha not healthy; schema resource unavailable');

try {
  const contents = await readSchemaResource();
} catch (e) {
  if (String(e.message).includes('error opening connection with Dgraph Alpha')) {
    // wait and retry the resource read
    await new Promise(r => setTimeout(r, 2000));
    return readSchemaResource();
  }
  throw e;
}

When it happens

Trigger: Reading the dgraph://schema MCP resource while the Alpha is down/unreachable or the connection string is wrong (bad host, HTTP port instead of 9080, TLS mismatch).

Common situations: AI client (e.g. Claude/IDE) requests the schema resource when the Dgraph cluster was stopped; misconfigured DGRAPH_ALPHA env in the MCP server launch config.

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: %v
• 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/630fa261785545e9. Report an issue: GitHub.