charmbracelet/gum · error

unable to start program: %w

Error message

unable to start program: %w

What it means

Gum pager wraps any error returned by tea.Program.Run() (the bubbletea TUI runtime) with this message. It means the pager's full-screen program failed to start or aborted mid-run — terminal incompatibility, I/O failure, or context cancellation propagated from the underlying renderer.

Source

Thrown at pager/command.go:55

		content:             o.Content,
		origContent:         o.Content,
		showLineNumbers:     o.ShowLineNumbers,
		lineNumberStyle:     o.LineNumberStyle.ToLipgloss(),
		softWrap:            o.SoftWrap,
		matchStyle:          o.MatchStyle.ToLipgloss(),
		matchHighlightStyle: o.MatchHighlightStyle.ToLipgloss(),
		keymap:              defaultKeymap(),
	}

	ctx, cancel := timeout.Context(o.Timeout)
	defer cancel()

	_, err := tea.NewProgram(
		m,
		tea.WithContext(ctx),
	).Run()
	if err != nil {
		return fmt.Errorf("unable to start program: %w", err)
	}

	return nil
}

View on GitHub (pinned to 4d089f9550)

Solutions

1. Run the command inside a real interactive terminal (TTY); avoid it in CI scripts.
2. Check TERM is set to a capable value (e.g. export TERM=xterm-256color).
3. Inspect the wrapped error (%w) to see the underlying bubbletea failure.
4. If the context is being cancelled, verify parent goroutine/signal handling.

Example fix

// before (in CI, no TTY)
git log | gum pager
// after
if [ -t 0 ] && [ -t 1 ]; then git log | gum pager; else git log | less; fi

if [ -t 0 ] && [ -t 1 ]; then git log | gum pager; else git log | less; fi

if ! out=$(git log | gum pager 2>&1); then echo "pager failed: $out"; git log | less; fi

When it happens

Trigger: Running `gum pager` in a non-TTY environment, a terminal that bubbletea cannot initialize (bad TERM, no /dev/tty), or the context passed via tea.WithContext(ctx) being cancelled before Run completes.

Common situations: CI jobs or cron jobs invoking gum pager without a TTY; SSH sessions with weird TERM settings; SIGINT/SIGTERM cancelling the parent context.

Related errors

• unable to run action: %w
• failed to start tea program: %w
• failed to run write: %w
• unable to pick selection: %w
• unable to pick selection: %w

AI-assisted analysis of charmbracelet/gum@4d089f9550 (2026-08-31). Data as JSON: /api/errors/96a1c0e90ead9ae5. Report an issue: GitHub.