{"record":{"id":"e55fd56e8eb4ac0f","repo":"dgraph-io/dgraph","slug":"failed-to-initiate-external-snapshot-stream-v","errorCode":null,"errorMessage":"failed to initiate external snapshot stream: %v","messagePattern":"failed to initiate external snapshot stream: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"dgraph/cmd/dgraphimport/import_client.go","lineNumber":96,"sourceCode":"\tglog.Info(\"[import] Initiating external snapshot stream\")\n\treq := &api.UpdateExtSnapshotStreamingStateRequest{\n\t\tStart: true,\n\t}\n\n\tconst maxRetryDuration = 60 * time.Second\n\tdeadline := time.Now().Add(maxRetryDuration)\n\tretryDelay := time.Second\n\n\tfor {\n\t\tresp, err := dc.UpdateExtSnapshotStreamingState(ctx, req)\n\t\tif err == nil {\n\t\t\tglog.Info(\"[import] External snapshot stream initiated successfully\")\n\t\t\treturn resp, nil\n\t\t}\n\n\t\tif !isRetryableError(err) || time.Now().After(deadline) {\n\t\t\tglog.Errorf(\"[import] failed to initiate external snapshot stream: %v\", err)\n\t\t\treturn nil, fmt.Errorf(\"failed to initiate external snapshot stream: %v\", err)\n\t\t}\n\n\t\tglog.Warningf(\"[import] transient error initiating snapshot stream, retrying in %v: %v\", retryDelay, err)\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn nil, ctx.Err()\n\t\tcase <-time.After(retryDelay):\n\t\t}\n\t\tretryDelay = min(retryDelay*2, 10*time.Second)\n\t}\n}\n\n// streamSnapshot takes a p directory and a set of group IDs and streams the data from the\n// p directory to the corresponding group IDs. It first scans the provided directory for\n// subdirectories named with numeric group IDs.\nfunc streamSnapshot(ctx context.Context, dc api.DgraphClient, baseDir string, groups []uint32) error {\n\tglog.Infof(\"[import] Starting to stream snapshot from directory: %s\", baseDir)\n","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/dgraph/cmd/dgraphimport/import_client.go#L78-L114","documentation":"The server rejected the request to start the external snapshot streaming session (UpdateExtSnapshotStreamingState with Start=true). The client retries only 'overloaded' errors for up to 60s; any other error (or exhausted deadline) is wrapped and returned. The cluster stays out of drain mode and streaming never begins.","triggerScenarios":"Alpha/Zero returns an error on UpdateExtSnapshotStreamingState(Start=true): connectivity loss, non-retryable server error, or 'overloaded with pending proposals' persisting beyond the 60s deadline; also raised when a non-retryable error occurs on the first attempt.","commonSituations":"Cluster under heavy Raft load (many writes during import), quorum loss / no leader elected, wrong endpoint, ACL interceptors rejecting the call, context canceled mid-retry (surfaced separately as ctx.Err).","solutions":["Inspect the wrapped cause (%v) for the server-side message (no leader, permission denied, overloaded...).","If 'overloaded': reduce write load, wait for Raft proposals to drain, then retry; the client already retries for 60s.","Verify cluster health (Zero leaders, Alpha group health) before initiating streaming.","Check ACL/auth setup so the gRPC call is authorized; confirm endpoint points at a live Alpha."],"exampleFix":"// before\nerr := dgraphimport.Import(ctx, \"alpha1:9080\", outDir) // cluster has no Zero quorum\n// after\n// ensure zero quorum & leaders first:\n//   kubectl exec zero-0 -- curl localhost:6080/state\nerr := dgraphimport.Import(ctx, \"alpha1:9080\", outDir)","handlingStrategy":"retry","validationCode":"// health-check before initiating\nresp, err := http.Get(\"http://alpha1:8080/health\")\nif err != nil || resp.StatusCode != http.StatusOK {\n    return fmt.Errorf(\"alpha not healthy; aborting snapshot import\")\n}","typeGuard":null,"tryCatchPattern":"err := dgraphimport.Import(ctx, addr, outDir)\nif err != nil && strings.Contains(err.Error(), \"failed to initiate external snapshot stream\") {\n    if strings.Contains(err.Error(), \"overloaded\") {\n        time.Sleep(30 * time.Second) // let Raft drain, then retry once\n        err = dgraphimport.Import(ctx, addr, outDir)\n    }\n}\nreturn err","preventionTips":["Run imports during low write load to avoid Raft proposal backlogs.","Confirm Zero quorum and leader election before starting.","Use a context with a generous but bounded timeout.","Keep ACL/auth tokens valid for the whole import window."],"tags":["grpc","raft","snapshot","retry","import"],"backgroundTag":"snapshot-stream-initiation-failed","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}