{"record":{"id":"dbd59c9e101b744f","repo":"wavetermdev/waveterm","slug":"starting-remote-file-stream-w","errorCode":null,"errorMessage":"starting remote file stream: %w","messagePattern":"starting remote file stream: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/remote/fileshare/wshfs/wshfs.go","lineNumber":78,"sourceCode":"\twriterRouteId := wshutil.MakeConnectionRouteId(conn.Host)\n\treader, streamMeta := broker.CreateStreamReader(readerRouteId, writerRouteId, 256*1024)\n\tdefer reader.Close()\n\tgo func() {\n\t\t<-ctx.Done()\n\t\treader.Close()\n\t}()\n\tbyteRange := \"\"\n\tif data.At != nil && data.At.Size > 0 {\n\t\tbyteRange = fmt.Sprintf(\"%d-%d\", data.At.Offset, data.At.Offset+int64(data.At.Size)-1)\n\t}\n\tremoteData := wshrpc.CommandRemoteFileStreamData{\n\t\tPath:       conn.Path,\n\t\tByteRange:  byteRange,\n\t\tStreamMeta: *streamMeta,\n\t}\n\tfileInfo, err := wshclient.RemoteFileStreamCommand(RpcClient, remoteData, &wshrpc.RpcOpts{Route: writerRouteId})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"starting remote file stream: %w\", err)\n\t}\n\tvar rawData []byte\n\tif fileInfo != nil && !fileInfo.IsDir {\n\t\trawData, err = io.ReadAll(reader)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"reading file stream: %w\", err)\n\t\t}\n\t}\n\trtnData := &wshrpc.FileData{Info: fileInfo}\n\tif len(rawData) > 0 {\n\t\trtnData.Data64 = base64.StdEncoding.EncodeToString(rawData)\n\t}\n\treturn rtnData, nil\n}\n\nfunc GetConnectionRouteId(ctx context.Context, path string) (string, error) {\n\tconn, err := parseConnection(ctx, path)\n\tif err != nil {","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/remote/fileshare/wshfs/wshfs.go#L60-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped error to determine the remote-side cause","Verify the connection to the host is established before reading (e.g. wsh conn status)","Confirm the remote file exists and is readable (Stat first)","Ensure remote end runs a wsh version supporting RemoteFileStream"],"exampleFix":"// before\ninfo, err := wshfs.Stat(ctx, path)\n// handle nothing, call Read directly\n// after\ninfo, err := wshfs.Stat(ctx, path)\nif err != nil {\n    return fmt.Errorf(\"cannot access %s: %w\", path, err) // fail fast before streaming\n}\ndata, err := wshfs.Read(ctx, wshrpc.FileData{Info: info})","handlingStrategy":"retry","validationCode":"info, err := wshfs.Stat(ctx, path) // pre-check reachability/existence\nif err != nil {\n    return fmt.Errorf(\"remote file not accessible %q: %w\", path, err)\n}","typeGuard":null,"tryCatchPattern":"out, err := wshfs.Read(ctx, data)\nif err != nil {\n    if strings.Contains(err.Error(), \"starting remote file stream\") {\n        // retry with backoff for transient connection issues\n        return retry(3, 500*time.Millisecond, func() error { _, e := wshfs.Read(ctx, data); return e })\n    }\n    return err\n}","preventionTips":["Ensure the remote connection is established before file operations","Stat the remote path first to fail fast on missing files","Check remote wsh version supports file streaming RPCs","Use connection health checks/keepalives for long sessions"],"tags":["go","rpc","network","streaming"],"backgroundTag":"rpc-stream-start-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}