wavetermdev/waveterm · error

initializing file with empty write: %w

Error message

initializing file with empty write: %w

What it means

streamWriteToFile truncates the destination by issuing a FileWriteCommand with empty data (Data64 = "") before streaming chunks. If this initial write RPC fails, the error is wrapped as "initializing file with empty write" — nothing was streamed yet.

Source

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

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

func streamWriteToFile(fileData wshrpc.FileData, reader io.Reader) error {
	// First truncate the file with an empty write
	emptyWrite := fileData
	emptyWrite.Data64 = ""
	err := wshclient.FileWriteCommand(RpcClient, emptyWrite, &wshrpc.RpcOpts{Timeout: fileTimeout})
	if err != nil {
		return fmt.Errorf("initializing file with empty write: %w", err)
	}

	const chunkSize = wshrpc.FileChunkSize // 32KB chunks
	buf := make([]byte, chunkSize)
	totalWritten := int64(0)

	for {
		n, err := reader.Read(buf)
		if err == io.EOF {
			break
		}
		if err != nil {
			return fmt.Errorf("reading input: %w", err)
		}

		// Check total size
		totalWritten += int64(n)
		if totalWritten > MaxFileSize {

View on GitHub (pinned to a4447c1563)

Solutions

1. Check write permission on the destination file and its directory.
2. Confirm the destination is a file, not a directory, and the path is correct.
3. Verify the remote connection is alive and retry the command.
4. Increase fileTimeout for slow links.

Example fix

// before
cat data.bin | wsh cp - /remote/readonly/data.bin
// after
cat data.bin | wsh cp - /remote/home/user/data.bin

if info, err := wshclient.FileInfoCommand(RpcClient, fileData, &wshrpc.RpcOpts{Timeout: fileTimeout}); err == nil && info.IsDir {
    return fmt.Errorf("destination %s is a directory", fileData.Info.Path)
}

if err := streamWriteToFile(fileData, reader); err != nil {
    if strings.Contains(err.Error(), "initializing file with empty write") {
        // check destination permissions/type before retrying
    }
}

When it happens

Trigger: First FileWriteCommand in `wsh cp -`/append-style streaming fails: destination file not writable, file is actually a directory, remote connection down, or RPC timeout (fileTimeout).

Common situations: Piping data to a read-only or protected remote path; destination path points at a directory; SSH connection dropped right as the write started.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• creating file: %w
• accessing file %s: %w
• reading directory %s: %w
• reading file %s: %w
• error creating listener at %v: %v

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