{"record":{"id":"630fa261785545e9","repo":"dgraph-io/dgraph","slug":"error-opening-connection-with-dgraph-alpha-w","errorCode":null,"errorMessage":"error opening connection with Dgraph Alpha: %w","messagePattern":"error opening connection with Dgraph Alpha: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"dgraph/cmd/mcp/mcp_server.go","lineNumber":335,"sourceCode":"\t\tresp, err := txn.Query(ctx, \"schema {}\")\n\t\tif err != nil {\n\t\t\treturn mcp.NewToolResultErrorFromErr(\"Error running query\", err), nil\n\t\t}\n\t\treturn mcp.NewToolResultText(string(resp.GetJson())), nil\n\t})\n\n\tschemaResource := mcp.NewResource(\n\t\t\"dgraph://schema\",\n\t\t\"dgraph_schema\",\n\t\tmcp.WithResourceDescription(\"The current Dgraph DQL schema\"),\n\t\tmcp.WithMIMEType(\"text/plain\"),\n\t)\n\n\ts.AddResource(schemaResource, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {\n\t\t// Execute operation\n\t\tconn, err := getConn(connectionString)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error opening connection with Dgraph Alpha: %w\", err)\n\t\t}\n\t\tresp, err := conn.NewTxn().Query(ctx, \"schema {}\")\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error running query: %w\", err)\n\t\t}\n\n\t\treturn []mcp.ResourceContents{\n\t\t\tmcp.TextResourceContents{\n\t\t\t\tURI:      \"dgraph://schema\",\n\t\t\t\tMIMEType: \"text/plain\",\n\t\t\t\tText:     string(resp.Json),\n\t\t\t},\n\t\t}, nil\n\t})\n\n\tcommonQueriesTool := mcp.NewTool(\"get_common_queries\",\n\t\tmcp.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.\"),\n\t\tmcp.WithToolAnnotation(mcp.ToolAnnotation{","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/dgraph/cmd/mcp/mcp_server.go#L317-L353","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Ensure the Dgraph Alpha is running and reachable at the configured gRPC address","Correct the connection string/port (9080) in the MCP server configuration","Check network/firewall between the MCP server host and the Alpha"],"exampleFix":"// before (env)\nDGRAPH_ALPHA=alpha:8080\n// after\nDGRAPH_ALPHA=alpha:9080","handlingStrategy":"retry","validationCode":"// Health-check before reading the schema resource\nconst health = await fetch('http://alpha:8080/health');\nif (!health.ok) throw new Error('Alpha not healthy; schema resource unavailable');","typeGuard":null,"tryCatchPattern":"try {\n  const contents = await readSchemaResource();\n} catch (e) {\n  if (String(e.message).includes('error opening connection with Dgraph Alpha')) {\n    // wait and retry the resource read\n    await new Promise(r => setTimeout(r, 2000));\n    return readSchemaResource();\n  }\n  throw e;\n}","preventionTips":["Keep the Dgraph cluster running for the lifetime of the MCP server","Validate DGRAPH_ALPHA host:port at MCP server startup","Monitor Alpha uptime and alert before clients request resources"],"tags":["network","mcp","grpc","connection"],"backgroundTag":"connection-refused","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}