wavetermdev/waveterm · error

starting remote file stream: %w

Error message

starting remote file stream: %w

What it means

This wraps a failure from wshclient.RemoteFileStreamCommand, the RPC sent to the remote connection's route to start streaming the file. The local side was ready (broker, route ids OK), but the remote side rejected or failed the stream start — e.g. the file does not exist, permission denied, or the connection route is unreachable. The wrapped err contains the actual cause.

Source

Thrown at pkg/remote/fileshare/wshfs/wshfs.go:78

	writerRouteId := wshutil.MakeConnectionRouteId(conn.Host)
	reader, streamMeta := broker.CreateStreamReader(readerRouteId, writerRouteId, 256*1024)
	defer reader.Close()
	go func() {
		<-ctx.Done()
		reader.Close()
	}()
	byteRange := ""
	if data.At != nil && data.At.Size > 0 {
		byteRange = fmt.Sprintf("%d-%d", data.At.Offset, data.At.Offset+int64(data.At.Size)-1)
	}
	remoteData := wshrpc.CommandRemoteFileStreamData{
		Path:       conn.Path,
		ByteRange:  byteRange,
		StreamMeta: *streamMeta,
	}
	fileInfo, err := wshclient.RemoteFileStreamCommand(RpcClient, remoteData, &wshrpc.RpcOpts{Route: writerRouteId})
	if err != nil {
		return nil, fmt.Errorf("starting remote file stream: %w", err)
	}
	var rawData []byte
	if fileInfo != nil && !fileInfo.IsDir {
		rawData, err = io.ReadAll(reader)
		if err != nil {
			return nil, fmt.Errorf("reading file stream: %w", err)
		}
	}
	rtnData := &wshrpc.FileData{Info: fileInfo}
	if len(rawData) > 0 {
		rtnData.Data64 = base64.StdEncoding.EncodeToString(rawData)
	}
	return rtnData, nil
}

func GetConnectionRouteId(ctx context.Context, path string) (string, error) {
	conn, err := parseConnection(ctx, path)
	if err != nil {

View on GitHub (pinned to a4447c1563)

Solutions

1. Inspect the wrapped error to determine the remote-side cause
2. Verify the connection to the host is established before reading (e.g. wsh conn status)
3. Confirm the remote file exists and is readable (Stat first)
4. Ensure remote end runs a wsh version supporting RemoteFileStream

Example fix

// before
info, err := wshfs.Stat(ctx, path)
// handle nothing, call Read directly
// after
info, err := wshfs.Stat(ctx, path)
if err != nil {
    return fmt.Errorf("cannot access %s: %w", path, err) // fail fast before streaming
}
data, err := wshfs.Read(ctx, wshrpc.FileData{Info: info})

info, err := wshfs.Stat(ctx, path) // pre-check reachability/existence
if err != nil {
    return fmt.Errorf("remote file not accessible %q: %w", path, err)
}

out, err := wshfs.Read(ctx, data)
if err != nil {
    if strings.Contains(err.Error(), "starting remote file stream") {
        // retry with backoff for transient connection issues
        return retry(3, 500*time.Millisecond, func() error { _, e := wshfs.Read(ctx, data); return e })
    }
    return err
}

When it happens

Trigger: Calling wshfs.Read for a path whose host's route is not connected (no remote connection established), the remote file does not exist or is inaccessible, or the remote connserver returns an error to RemoteFileStreamCommand.

Common situations: SSH connection dropped or never established so MakeConnectionRouteId(host) has no live route; typo in remote path; permission denied on the remote file; remote wsh version too old to support file streaming RPCs.

Related errors

• appending chunk to file: %w
• failed to reconnect to job manager: %w
• reading file stream: %w
• msg.error
• wcloud endpoint not set

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/dbd59c9e101b744f. Report an issue: GitHub.