vitessio/vitess · error

remote error: %v

Error message

remote error: %v

What it means

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.

Source

Thrown at go/vt/vtctl/vtctlclient/wrapper.go:65

	deadline, ok := ctx.Deadline()
	if ok {
		timeout = time.Until(deadline)
	}
	stream, err := client.ExecuteVtctlCommand(ctx, args, timeout)
	if err != nil {
		return fmt.Errorf("cannot execute remote command: %v", err)
	}

	// stream the result
	for {
		e, err := stream.Recv()
		switch err {
		case nil:
			recv(e)
		case io.EOF:
			return nil
		default:
			return fmt.Errorf("remote error: %v", err)
		}
	}
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Inspect the wrapped cause: gRPC status codes distinguish command failure (InvalidArgument/Unknown) from transport loss (Unavailable)
2. If the server rejected the command, fix the command arguments (keyspace/shard names, permissions) and re-run
3. For Unavailable/Canceled causes, check network stability and context deadlines before retrying
4. Remember partial side effects may have occurred; use idempotent vtctl commands when retrying

Example fix

// before
err := vtctlclient.RunCommandAndWait(ctx, server, args, recv, true)
// after
if err != nil && strings.Contains(err.Error(), "Unavailable") {
  err = vtctlclient.RunCommandAndWait(ctx, server, args, recv, true) // retry transport loss
}

// validate args server-side expectations before streaming
cmd := args[0]
if !knownVtctlCommands[cmd] {
  return fmt.Errorf("unknown vtctl command %q would fail remotely", cmd)
}

for {
  e, err := stream.Recv()
  switch {
  case err == nil: recv(e)
  case errors.Is(err, io.EOF): return nil
  default:
    if st, ok := status.FromError(err); ok && st.Code() == codes.Unavailable {
      return retryable(err)
    }
    return err
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• cannot dial to server %v: %v
• cannot execute remote command: %v
• failed to load static auth plugin. Plugin configured but grp
• ErrStreamClosed
• error parsing vschema statement `%s`: %v

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/cb47af4fd4071d96. Report an issue: GitHub.