What causes "pty mode is not supported on Windows" in wtfutil/wtf?

Disable PTY mode for the cmdrunner module (remove/set pty: false) on Windows

pty mode is not supported on Windows

Error message

pty mode is not supported on Windows

What it means

cmdrunner's PTY mode allocates a pseudo-terminal via Unix syscalls (SIGWINCH) and the creack/pty library. On Windows that is unsupported, so the build-tagged pty_windows.go implementation of runCommandPty unconditionally returns this stub error. PTY output simply cannot be used on Windows.

Source

Thrown at modules/cmdrunner/pty_windows.go:13

//go:build windows

package cmdrunner

import (
	"errors"
	"os/exec"
)

// runCommandPty is not supported on Windows. PTY mode requires Unix-specific
// syscalls (SIGWINCH) and the creack/pty library which does not support Windows.
func runCommandPty(widget *Widget, cmd *exec.Cmd) error {
	return errors.New("pty mode is not supported on Windows")
}

View on GitHub (pinned to bb838c1ccb)

Solutions

Disable PTY mode for the cmdrunner module (remove/set pty: false) on Windows
Run wtfutil under WSL and configure PTY there instead of native Windows
Drop PTY mode and capture plain stdout; redesign the command to not require a TTY
If PTY is essential, use a Unix host

Example fix

# before (config.yml)
cmdrunner:
  args: ["watch", "ls"]
  pty: true
# after (Windows)
cmdrunner:
  args: ["ls"]
  pty: false

Defensive patterns

Strategy: fallback

Validate before calling

if runtime.GOOS == "windows" && cfg.Bool("pty") {
    return errors.New("disable pty on Windows")
}

Type guard

func ptySupported() bool { return runtime.GOOS != "windows" }

Try / catch

if err := runCommand(widget, cmd); err != nil {
    if strings.Contains(err.Error(), "pty mode is not supported") {
        return runCommandPlain(widget, cmd) // fallback to non-PTY
    }
    return err
}

Prevention

Gate pty: true on GOOS in config generation scripts
Keep separate config profiles for Windows vs Unix
Prefer commands that don't require a TTY in widgets
Use WSL when PTY behavior is required on Windows machines

When it happens

Trigger: Configuring a cmdrunner widget with PTY mode enabled (pty: true in the module settings) on a Windows build of wtfutil; any code path that calls runCommandPty on the windows build.

Common situations: Sharing a config.yml between macOS/Linux and Windows machines; following Linux-focused tutorials that enable pty for interactive commands (top, htop, watch); CI validating configs cross-platform.

Related errors

AI-assisted analysis of wtfutil/wtf@bb838c1ccb (2026-09-03). Data as JSON: /api/errors/1c61ff20aee3e194. Report an issue: GitHub.