{"record":{"id":"a660ca3ed3401f78","repo":"dgraph-io/dgraph","slug":"failed-to-start-external-snapshot-stream-for-group","errorCode":null,"errorMessage":"failed to start external snapshot stream for group %d: %w","messagePattern":"failed to start external snapshot stream for group (.+?): %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"dgraph/cmd/dgraphimport/import_client.go","lineNumber":172,"sourceCode":"\t\tDropData: false,\n\t}\n\tif _, err := dc.UpdateExtSnapshotStreamingState(ctx, req); err != nil {\n\t\tglog.Errorf(\"[import] failed to disable drain mode: %v\", err)\n\t\treturn fmt.Errorf(\"failed to disable drain mode: %v\", err)\n\t}\n\tglog.Info(\"[import] successfully disable drain mode\")\n\treturn nil\n}\n\n// streamSnapshotForGroup handles the actual data streaming process for a single group.\n// It opens the BadgerDB at the specified directory and streams all data to the server.\nfunc streamSnapshotForGroup(ctx context.Context, dc api.DgraphClient, pdir string, groupId uint32) error {\n\tglog.Infof(\"Opening stream for group %d from directory %s\", groupId, pdir)\n\n\t// Initialize stream with the server\n\tout, err := dc.StreamExtSnapshot(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to start external snapshot stream for group %d: %w\", groupId, err)\n\t}\n\tdefer func() {\n\t\t_ = out.CloseSend()\n\t}()\n\n\t// Open the BadgerDB instance at the specified directory\n\topt := badger.DefaultOptions(pdir)\n\topt.ReadOnly = true\n\tps, err := badger.OpenManaged(opt)\n\tif err != nil {\n\t\tglog.Errorf(\"failed to open BadgerDB at [%s]: %v\", pdir, err)\n\t\treturn fmt.Errorf(\"failed to open BadgerDB at [%v]: %v\", pdir, err)\n\t}\n\tdefer func() {\n\t\tif err := ps.Close(); err != nil {\n\t\t\tglog.Warningf(\"[import] Error closing BadgerDB: %v\", err)\n\t\t}\n\t}()","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/dgraph/cmd/dgraphimport/import_client.go#L154-L190","documentation":"Returned by streamSnapshotForGroup when the initial dc.StreamExtSnapshot(ctx) bidirectional-stream call fails to open. The error wraps the underlying gRPC error with the group ID for context. Without this stream the snapshot data cannot be sent, so the function aborts before touching BadgerDB.","triggerScenarios":"Calling StreamExtSnapshot on a DgraphClient whose connection is down; server does not expose the StreamExtSnapshot RPC (version mismatch); context cancelled/deadline exceeded before the stream is established.","commonSituations":"Wrong --alpha hostname/port in the import command; Alpha restarted mid-import; TLS/mTLS mismatch preventing the gRPC channel; client and server binary versions out of sync.","solutions":["Verify Alpha connectivity (grpcurl or dgraph ping) before running the import.","Check that the server supports StreamExtSnapshot; upgrade client/server to matching versions.","Inspect the wrapped gRPC status code: Unavailable/DeadlineExceeded indicates network or timeout, Unimplemented indicates version mismatch.","Increase the gRPC context timeout for large operations.","Retry the import after transient network failures."],"exampleFix":"// before\nout, err := dc.StreamExtSnapshot(ctx)\nif err != nil {\n\treturn fmt.Errorf(\"failed to start external snapshot stream for group %d: %w\", groupId, err)\n}\n// after\nout, err := dc.StreamExtSnapshot(ctx)\nif err != nil {\n\tif s, ok := status.FromError(err); ok && s.Code() == codes.Unavailable {\n\t\treturn fmt.Errorf(\"alpha unreachable for group %d, check server address/health: %w\", groupId, err)\n\t}\n\treturn fmt.Errorf(\"failed to start external snapshot stream for group %d: %w\", groupId, err)\n}","handlingStrategy":"validation","validationCode":"conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))\nif err != nil {\n\treturn fmt.Errorf(\"cannot reach alpha %s: %w\", addr, err)\n}\nif err := conn.Invoke(ctx, \"/grpc.health.v1.Health/Check\", &health.HealthCheckRequest{}, &health.HealthCheckResponse{}); err != nil {\n\treturn fmt.Errorf(\"alpha unhealthy: %w\", err)\n}","typeGuard":"func isStreamSetupFailure(err error) bool {\n\tif s, ok := status.FromError(err); ok {\n\t\tswitch s.Code() {\n\t\tcase codes.Unavailable, codes.Unimplemented, codes.DeadlineExceeded:\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}","tryCatchPattern":"out, err := dc.StreamExtSnapshot(ctx)\nif err != nil {\n\tif s, ok := status.FromError(err); ok && s.Code() == codes.Unimplemented {\n\t\treturn fmt.Errorf(\"server does not support StreamExtSnapshot; upgrade server\")\n\t}\n\treturn err\n}","preventionTips":["Verify the Alpha address/port before running the import.","Keep client and server versions in lockstep.","Run imports directly against Alpha, not through short-timeout LBs.","Set adequate context deadlines before opening the stream."],"tags":["grpc","network","stream","snapshot-import"],"backgroundTag":"grpc-stream-setup-failed","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}