What causes "failed to execute command: %s" in sqshq/sampler?

Inspect the wrapped underlying error after the colon and address it directly

failed to execute command: %s

Error message

failed to execute command: %s

What it means

The PTY interactive shell wraps errors from starting the command on the pseudo-terminal into "failed to execute command: <underlying error>". On repeated failures past errorThreshold it closes the PTY file and nils item.ptyShell to restart the session cleanly. The actionable information is the wrapped underlying error.

Source

Thrown at data/int_pty.go:78

			return err
		}
		time.Sleep(startupTimeout) // TODO wait until cmd complete
	}

	return nil
}

func (s *PtyInteractiveShell) execute() (string, error) {

	_, err := io.WriteString(s.file, fmt.Sprintf(" %s\n", s.item.sampleScript))
	if err != nil {
		s.errCount++
		if s.errCount > errorThreshold {
			_ = s.cmd.Wait()
			_ = s.file.Close()
			s.item.ptyShell = nil // restart session
		}
		return "", fmt.Errorf("failed to execute command: %s", err)
	}

	softTimeout := make(chan bool, 1)
	hardTimeout := make(chan bool, 1)

	go func() {
		time.Sleep(s.getAwaitTimeout() / 2)
		softTimeout <- true
		time.Sleep(s.getAwaitTimeout() * 100)
		hardTimeout <- true
	}()

	var builder strings.Builder
	softTimeoutElapsed := false

await:
	for {
		select {

View on GitHub (pinned to 9bc7ba732d)

Solutions

Inspect the wrapped underlying error after the colon and address it directly
Use absolute executable paths and ensure execute permissions
Confirm PTY support on the host (enough ptys available; not a restricted container without /dev/ptmx)
Let the session restart logic work: after errorThreshold the library rebuilds the shell; fix the root cause so retries succeed
On Windows switch to the basic shell since PTY is not supported there

Example fix

// before
script: pty-runner
// after
script: /usr/local/bin/pty-runner  # exists, +x, PATH-independent

Defensive patterns

Strategy: try-catch

Validate before calling

path, err := exec.LookPath(cmdName); if err != nil || runtime.GOOS == "windows" { fall back to basic shell }

Try / catch

out, err := ptyShell.execute()
if err != nil {
    log.Printf("PTY exec failed: %v", err) // root cause is wrapped after the colon
    // session auto-restarts after errorThreshold; monitor repeated occurrences
}

Prevention

Prefer absolute paths and +x permissions for PTY-run scripts
Check /dev/ptmx availability in containers
Don't run PTY items on Windows

When it happens

Trigger: cmd.Start (or PTY setup) failing while executing a command through PtyInteractiveShell — missing executable, invalid args, PTY open failure — or accumulated session errors exceeding errorThreshold.

Common situations: Same class as basic: command not found in the service's PATH, script permissions, PTY resource exhaustion on the host, binary incompatible with the OS.

Related errors

AI-assisted analysis of sqshq/sampler@9bc7ba732d (2026-09-06). Data as JSON: /api/errors/78cd36dedb2ec783. Report an issue: GitHub.