What causes "error reading term file: %w" in wavetermdev/waveterm?

Inspect the wrapped underlying error for the root cause

error reading term file: %w

Error message

error reading term file: %w

What it means

Returned when reading the term file (terminal capture file) fails, e.g. it does not exist or is unreadable. The underlying error is wrapped with %w.

Source

Thrown at pkg/wshrpc/wshserver/wshserver.go:858

	if data.Size <= 0 {
		return nil, fmt.Errorf("size must be greater than 0")
	}
	waveFile, err := filestore.WFS.Stat(ctx, data.BlockId, wavebase.BlockFile_Term)
	if err == fs.ErrNotExist {
		return &wshrpc.CommandDebugTermRtnData{}, nil
	}
	if err != nil {
		return nil, fmt.Errorf("error statting term file: %w", err)
	}
	readSize := data.Size
	dataLength := waveFile.DataLength()
	if readSize > dataLength {
		readSize = dataLength
	}
	readOffset := waveFile.Size - readSize
	readOffset, readData, err := filestore.WFS.ReadAt(ctx, data.BlockId, wavebase.BlockFile_Term, readOffset, readSize)
	if err != nil {
		return nil, fmt.Errorf("error reading term file: %w", err)
	}
	return &wshrpc.CommandDebugTermRtnData{
		Offset: readOffset,
		Data64: base64.StdEncoding.EncodeToString(readData),
	}, nil
}

func (ws *WshServer) WaveInfoCommand(ctx context.Context) (*wshrpc.WaveInfoData, error) {
	return &wshrpc.WaveInfoData{
		Version:   wavebase.WaveVersion,
		ClientId:  wstore.GetClientId(),
		BuildTime: wavebase.BuildTime,
		ConfigDir: wavebase.GetWaveConfigDir(),
		DataDir:   wavebase.GetWaveDataDir(),
	}, nil
}

func (ws *WshServer) MacOSVersionCommand(ctx context.Context) (string, error) {

View on GitHub (pinned to a4447c1563)

Solutions

Inspect the wrapped underlying error for the root cause
Retry the call if the failure is transient
Verify the block's term file data is intact (Stat succeeds but ReadAt fails indicates data-level corruption)

Defensive patterns

Strategy: retry

Try / catch

var resp *wshrpc.CommandDebugTermRtnData
var err error
for i := 0; i < 3; i++ {
    resp, err = client.DebugTermCommand(ctx, data)
    if err == nil || !strings.Contains(err.Error(), "error reading term file") {
        break
    }
    time.Sleep(100 * time.Millisecond)
}

Prevention

Retry transient IO failures with backoff
Alert on repeated read failures (may indicate corruption)
Keep block term files within expected size bounds

When it happens

Trigger: WFS.ReadAt fails while reading the requested tail range of the terminal debug file (storage backend error, IO failure, data unavailable).

Common situations: Storage corruption of the block's term data; transient IO errors on the backing store; permission issues on the storage layer.

Related errors

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