{"record":{"id":"cb47af4fd4071d96","repo":"vitessio/vitess","slug":"remote-error-v","errorCode":null,"errorMessage":"remote error: %v","messagePattern":"remote error: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtctl/vtctlclient/wrapper.go","lineNumber":65,"sourceCode":"\tdeadline, ok := ctx.Deadline()\n\tif ok {\n\t\ttimeout = time.Until(deadline)\n\t}\n\tstream, err := client.ExecuteVtctlCommand(ctx, args, timeout)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot execute remote command: %v\", err)\n\t}\n\n\t// stream the result\n\tfor {\n\t\te, err := stream.Recv()\n\t\tswitch err {\n\t\tcase nil:\n\t\t\trecv(e)\n\t\tcase io.EOF:\n\t\t\treturn nil\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"remote error: %v\", err)\n\t\t}\n\t}\n}\n","sourceCodeStart":47,"sourceCodeEnd":69,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtctl/vtctlclient/wrapper.go#L47-L69","documentation":"While streaming results, each stream.Recv() error other than nil and io.EOF is returned as 'remote error: <cause>'. This is the mid-stream failure path: the command started and some events may already have been delivered to recv, but the stream broke before EOF. It represents the server-side execution error or transport failure propagated to the client.","triggerScenarios":"Calling RunCommandAndWait and the event stream's Recv() returns a non-EOF error: server-side command failure delivered over gRPC status, connection reset mid-stream, or context cancellation.","commonSituations":"The vtctl command itself failed remotely (e.g. invalid keyspace) and the server sent a gRPC error; network interruption during a long stream; client context cancelled/expired while streaming.","solutions":["Inspect the wrapped cause: gRPC status codes distinguish command failure (InvalidArgument/Unknown) from transport loss (Unavailable)","If the server rejected the command, fix the command arguments (keyspace/shard names, permissions) and re-run","For Unavailable/Canceled causes, check network stability and context deadlines before retrying","Remember partial side effects may have occurred; use idempotent vtctl commands when retrying"],"exampleFix":"// before\nerr := vtctlclient.RunCommandAndWait(ctx, server, args, recv, true)\n// after\nif err != nil && strings.Contains(err.Error(), \"Unavailable\") {\n  err = vtctlclient.RunCommandAndWait(ctx, server, args, recv, true) // retry transport loss\n}","handlingStrategy":"try-catch","validationCode":"// validate args server-side expectations before streaming\ncmd := args[0]\nif !knownVtctlCommands[cmd] {\n  return fmt.Errorf(\"unknown vtctl command %q would fail remotely\", cmd)\n}","typeGuard":null,"tryCatchPattern":"for {\n  e, err := stream.Recv()\n  switch {\n  case err == nil: recv(e)\n  case errors.Is(err, io.EOF): return nil\n  default:\n    if st, ok := status.FromError(err); ok && st.Code() == codes.Unavailable {\n      return retryable(err)\n    }\n    return err\n  }\n}","preventionTips":["Check the wrapped gRPC status code before retrying","Use idempotent vtctl commands so re-runs are safe","Watch for partial event delivery; recv may have already consumed events"],"tags":["go","grpc","streaming","vtctl","remote-error"],"backgroundTag":"remote-stream-error","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}