wavetermdev/waveterm · error

starting file stream: %w

Error message

starting file stream: %w

What it means

After setting up the stream reader, the CLI issues a FileStreamCommand RPC to the remote host to start streaming the file. If that RPC fails (connection error, remote rejects the request, timeout), the error is wrapped with 'starting file stream:'.

Source

Thrown at cmd/wsh/cmd/wshcmd-file-util.go:122

	}
	conn, err := connparse.ParseURI(fileData.Info.Path)
	if err != nil {
		return fmt.Errorf("parsing file path: %w", err)
	}
	writerRouteId := wshutil.MakeConnectionRouteId(conn.Host)
	reader, streamMeta := broker.CreateStreamReader(readerRouteId, writerRouteId, 256*1024)
	defer reader.Close()
	go func() {
		<-ctx.Done()
		reader.Close()
	}()
	data := wshrpc.CommandFileStreamData{
		Info:       fileData.Info,
		StreamMeta: *streamMeta,
	}
	_, err = wshclient.FileStreamCommand(RpcClient, data, nil)
	if err != nil {
		return fmt.Errorf("starting file stream: %w", err)
	}
	_, err = io.Copy(writer, reader)
	return err
}

func fixRelativePaths(path string) (string, error) {
	conn, err := connparse.ParseURI(path)
	if err != nil {
		return "", err
	}
	if conn.Scheme == connparse.ConnectionTypeWsh {
		if conn.Host == connparse.ConnHostCurrent {
			conn.Host = RpcContext.Conn
			fixedPath, err := fileutil.FixPath(conn.Path)
			if err != nil {
				return "", err
			}
			conn.Path = fixedPath

View on GitHub (pinned to a4447c1563)

Solutions

1. Re-run the command to confirm connectivity; check `wsh conn status` for the target host.
2. Verify the file path exists and is readable on the remote host (`wsh file info <path>`).
3. Update wsh on the remote host to match the terminal version; restart the connection.
4. Increase the RPC timeout or check network/SSH stability if it is a transient drop.

info, err := wshclient.FileInfoCommand(RpcClient, fileData, &wshrpc.RpcOpts{Timeout: fileTimeout})
if err != nil {
    return fmt.Errorf("file unreachable, skipping stream: %w", err)
}

err := streamReadFromFile(ctx, fileData, out)
if err != nil && strings.Contains(err.Error(), "starting file stream") {
    // check connectivity, refresh connection, then retry once
    return fmt.Errorf("stream start failed: %w", err)
}

When it happens

Trigger: Remote wsh server not running or unreachable, the remote rejects FileStreamCommand (path not readable, permission denied), RPC timeout, or the stream route vanished because the connection dropped mid-setup.

Common situations: Cats a file on a remote host whose wsh server is stale (version mismatch after terminal update), SSH connection dropped, reading a file the remote user lacks permission for.

Related errors

• nil wshrpc passed to wshclient
• file info is required
• no route id available
• getting file info: %w
• removing file: %w

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