yudai/gotty · error

failed to start command `%s`

Error message

failed to start command `%s`

What it means

Wrapped pty.Start error in LocalCommand.New: the configured command could not be launched under a pseudo-terminal — commonly exec not-found, exec permission denied, or PTY allocation failure. The command name is interpolated into the message; a known todo notes the half-started cmd may leak.

Source

Thrown at backend/localcommand/local_command.go:37

type LocalCommand struct {
	command string
	argv    []string

	closeSignal  syscall.Signal
	closeTimeout time.Duration

	cmd       *exec.Cmd
	pty       *os.File
	ptyClosed chan struct{}
}

func New(command string, argv []string, options ...Option) (*LocalCommand, error) {
	cmd := exec.Command(command, argv...)

	pty, err := pty.Start(cmd)
	if err != nil {
		// todo close cmd?
		return nil, errors.Wrapf(err, "failed to start command `%s`", command)
	}
	ptyClosed := make(chan struct{})

	lcmd := &LocalCommand{
		command: command,
		argv:    argv,

		closeSignal:  DefaultCloseSignal,
		closeTimeout: DefaultCloseTimeout,

		cmd:       cmd,
		pty:       pty,
		ptyClosed: ptyClosed,
	}

	for _, option := range options {
		option(lcmd)
	}

View on GitHub (pinned to a080c85cbc)

Solutions

1. Verify the command exists in the server's PATH and is executable
2. Check ulimit/process limits if PTY allocation is the failing step
3. Ensure cmd.Wait/Process cleanup runs on start failure to avoid zombie processes

When it happens

Trigger: Thrown at backend/localcommand/local_command.go:37 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of yudai/gotty@a080c85cbc (2026-09-02). Data as JSON: /api/errors/ff83d27e8009c93d. Report an issue: GitHub.