What causes "failed to read app file: %w" in wavetermdev/waveterm?

Inspect the wrapped underlying error for the exact cause

failed to read app file: %w

Error message

failed to read app file: %w

What it means

ReadAppFileCommand wraps any read error that is not os.ErrNotExist as 'failed to read app file'. Missing files are handled gracefully (NotFound: true), so this error indicates a genuine read failure in the app store.

Source

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

		Entries:      entries,
		EntryCount:   result.EntryCount,
		TotalEntries: result.TotalEntries,
		Truncated:    result.Truncated,
	}, nil
}

func (ws *WshServer) ReadAppFileCommand(ctx context.Context, data wshrpc.CommandReadAppFileData) (*wshrpc.CommandReadAppFileRtnData, error) {
	if data.AppId == "" {
		return nil, fmt.Errorf("must provide an appId to ReadAppFileCommand")
	}
	fileData, err := waveappstore.ReadAppFile(data.AppId, data.FileName)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return &wshrpc.CommandReadAppFileRtnData{
				NotFound: true,
			}, nil
		}
		return nil, fmt.Errorf("failed to read app file: %w", err)
	}
	return &wshrpc.CommandReadAppFileRtnData{
		Data64: base64.StdEncoding.EncodeToString(fileData.Contents),
		ModTs:  fileData.ModTs,
	}, nil
}

func (ws *WshServer) WriteAppFileCommand(ctx context.Context, data wshrpc.CommandWriteAppFileData) error {
	if data.AppId == "" {
		return fmt.Errorf("must provide an appId to WriteAppFileCommand")
	}
	contents, err := base64.StdEncoding.DecodeString(data.Data64)
	if err != nil {
		return fmt.Errorf("failed to decode data64: %w", err)
	}
	return waveappstore.WriteAppFile(data.AppId, data.FileName, contents)
}

View on GitHub (pinned to a4447c1563)

Solutions

Inspect the wrapped underlying error for the exact cause
Check read permissions on the app storage directory/file
Verify disk health / free space and retry
Confirm the app store path (wave home) is accessible to the process

Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure app storage is readable beforehand
if _, err := os.Stat(appStorageDir); err != nil {
    return fmt.Errorf("app storage inaccessible: %w", err)
}

Try / catch

file, err := client.ReadAppFileCommand(ctx, data)
if err != nil {
    if strings.Contains(err.Error(), "failed to read app file") {
        var cause error
        errors.As(err, &cause)
        // check permissions/IO and retry
    }
    return err
}

Prevention

Check permissions on the wave app store directory
Use errors.As to inspect the wrapped cause
Treat os.ErrNotExist separately (returned as NotFound, not this error)

When it happens

Trigger: waveappstore.ReadAppFile fails with a non-ErrNotExist error: permission denied on the app storage file, IO failure, or app storage corruption.

Common situations: Filesystem permissions on the wave app store directory; disk errors; app file locked or unreadable.

Related errors

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