dgraph-io/dgraph · error

failed to connect to endpoint [%s]: %w

Error message

failed to connect to endpoint [%s]: %w

What it means

dgo.Open failed to establish a gRPC connection to the supplied endpoint; newClient wraps the original error with the endpoint for context. This is a connectivity/handshake failure, not a validation error — the string was non-empty but unusable.

Source

Thrown at dgraph/cmd/dgraphimport/import_client.go:36

	"github.com/dgraph-io/badger/v4"
	"github.com/dgraph-io/dgo/v250"
	"github.com/dgraph-io/dgo/v250/protos/api"
	"github.com/dgraph-io/ristretto/v2/z"

	"github.com/golang/glog"
	"golang.org/x/sync/errgroup"
)

// newClient creates a new import client with the specified endpoint and gRPC options.
func newClient(connectionString string) (api.DgraphClient, error) {
	if connectionString == "" {
		return nil, fmt.Errorf("connection string cannot be empty")
	}

	dg, err := dgo.Open(connectionString)
	if err != nil {
		return nil, fmt.Errorf("failed to connect to endpoint [%s]: %w", connectionString, err)
	}

	glog.Infof("[import] Successfully connected to Dgraph endpoint: %s", connectionString)
	return dg.GetAPIClients()[0], nil
}

func Import(ctx context.Context, connectionString string, bulkOutDir string) error {
	if bulkOutDir == "" {
		return fmt.Errorf("bulk output directory cannot be empty")
	}

	dg, err := newClient(connectionString)
	if err != nil {
		return err
	}
	resp, err := initiateSnapshotStream(ctx, dg)
	if err != nil {
		return err

View on GitHub (pinned to 759e242be6)

Solutions

1. Verify the Alpha gRPC port: curl the HTTP health port and confirm the process is up (kubectl get pods / docker ps).
2. Test reachability: grpcurl or nc -zv <host> 9080.
3. If the cluster uses TLS/ACL, supply the matching connection-string options (certs, tls) to dgo.Open.
4. Read the wrapped cause (%w) with errors.Unwrap / %v to distinguish DNS vs connection refused vs TLS errors.

Example fix

// before
dg, err := dgraphimport.Import(ctx, "localhost:8080", outDir) // HTTP port, not gRPC
// after
dg, err := dgraphimport.Import(ctx, "localhost:9080", outDir)

conn, err := net.DialTimeout("tcp", "alpha1:9080", 3*time.Second)
if err != nil {
    return fmt.Errorf("alpha gRPC port unreachable before dial: %v", err)
}
conn.Close()

if err := dgraphimport.Import(ctx, addr, outDir); err != nil {
    if strings.Contains(err.Error(), "failed to connect to endpoint") {
        // transient? retry with backoff; else surface unwrapped cause
        var cause error = errors.Unwrap(errors.Unwrap(err))
        return fmt.Errorf("dial failed: %v", cause)
    }
    return err
}

When it happens

Trigger: Alpha down or unreachable, wrong host/port (gRPC 9080 vs HTTP 8080), DNS failure, TLS mismatch (plain connection to a TLS-enabled cluster or vice-versa), malformed connection string options.

Common situations: Cluster not yet started, k8s service name/port wrong, security mode (TLS) enabled client-side not configured, firewall/network policy blocking 9080, typo in host.

Related errors

• error opening connection with Dgraph Alpha: %v
• error opening connection with Dgraph Alpha: %w
• failed to establish stream with leader: %v
• connection string cannot be empty
• failed to initiate external snapshot stream: %v

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