User redirected to docsite to learn more about ARM64 transla

Error message

User redirected to docsite to learn more about ARM64 translation, exiting

What it means

GetClientPlatform runs `uname -sm` on the remote WSL host via the shell client to detect OS/architecture for wsh installation. If the command itself fails (non-zero exit, connection error), this error wraps both the underlying error and stderr. It is a remote command execution failure, not a parse failure.

Source

Thrown at emain/emain-platform.ts:63

    if (!fullConfig.settings["app:dismissarchitecturewarning"] && app.runningUnderARM64Translation) {
        console.log("Running under ARM64 translation, alerting user");
        const dialogOpts: Electron.MessageBoxOptions = {
            type: "warning",
            buttons: ["Dismiss", "Learn More"],
            title: "Wave has detected a performance issue",
            message: `Wave is running in ARM64 translation mode which may impact performance.\n\nRecommendation: Download the native ARM64 version from our website for optimal performance.`,
        };

        const choice = dialog.showMessageBoxSync(null, dialogOpts);
        if (choice === 1) {
            // Open the documentation URL
            console.log("User chose to learn more");
            fireAndForget(() =>
                shell.openExternal(
                    "https://docs.waveterm.dev/faq#why-does-wave-warn-me-about-arm64-translation-when-it-launches"
                )
            );
            throw new Error("User redirected to docsite to learn more about ARM64 translation, exiting");
        } else {
            console.log("User dismissed the dialog");
        }
    }
}

/**
 * Gets the path to the old Wave home directory (defaults to `~/.waveterm`).
 * @returns The path to the directory if it exists and contains valid data for the current app, otherwise null.
 */
function getWaveHomeDir(): string {
    let home = process.env[WaveHomeVarName];
    if (!home) {
        const homeDir = app.getPath("home");
        if (homeDir) {
            home = path.join(homeDir, `.${waveDirName}`);
        }
    }

View on GitHub (pinned to a4447c1563)

Solutions

Inspect the wrapped stderr in the message to find the remote-side cause
Verify the WSL instance is running (`wsl -l -v` shows Running) and retry
Confirm `uname` exists in the distro (`command -v uname`)
Re-test the underlying shell connection used by genconn

Example fix

// before
os, arch, err := GetClientPlatform(ctx, shell) // opaque failure
// after
if ok, _ := genconn.RunSimpleCommand(ctx, shell, genconn.CommandSpec{Cmd: "command -v uname"}); ok == "" {
    // ensure the distro image has coreutils before installing wsh
}
os, arch, err := GetClientPlatform(ctx, shell)

Defensive patterns

Strategy: retry

Validate before calling

_, _, err := genconn.RunSimpleCommand(ctx, shell, genconn.CommandSpec{Cmd: "uname -sm"})
if err != nil {
    return fmt.Errorf("remote shell not ready for wsh install: %w", err)
}

Try / catch

os, arch, err := wslconn.GetClientPlatform(ctx, shell)
if err != nil {
    var werr error
    errors.As(err, &werr) // inspect wrapped stderr in message
    return fmt.Errorf("platform detection failed: %w", err)
}

Prevention

Ensure the WSL instance is running before installing wsh
Retry once after a short delay — first command after boot can fail
Confirm coreutils/uname exists in minimal distro images

When it happens

Trigger: InstallWsh calls GetClientPlatform; genconn.RunSimpleCommand returns an error (shell died, connection dropped, `uname` missing, permission denied).

Common situations: WSL instance shut down mid-operation; broken wsh/ssh transport; minimal distro image without coreutils; shell startup errors polluting the session.

Related errors

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