charmbracelet/gum · error

failed to start tea program: %w

Error message

failed to start tea program: %w

What it means

gum table could not start its Bubble Tea (tea.Program) interactive UI. The underlying tea error (terminal incompatibility, context cancellation, output setup failure) is wrapped with %w. Without the TUI, no selection can be presented.

Source

Thrown at table/command.go:160

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

	m := model{
		table:     table,
		showHelp:  o.ShowHelp,
		hideCount: o.HideCount,
		help:      help.New(),
		keymap:    defaultKeymap(),
		padding:   []int{top, right, bottom, left},
	}
	tm, err := tea.NewProgram(
		m,
		tea.WithOutput(os.Stderr),
		tea.WithContext(ctx),
	).Run()
	if err != nil {
		return fmt.Errorf("failed to start tea program: %w", err)
	}

	if tm == nil {
		return fmt.Errorf("failed to get selection")
	}

	m = tm.(model)
	if o.ReturnColumn > 0 && o.ReturnColumn <= len(m.selected) {
		if err = writer.Write([]string{m.selected[o.ReturnColumn-1]}); err != nil {
			return fmt.Errorf("failed to write col %d of selected row: %w", o.ReturnColumn, err)
		}
	} else {
		if err = writer.Write([]string(m.selected)); err != nil {
			return fmt.Errorf("failed to write selected row: %w", err)
		}
	}

	writer.Flush()

View on GitHub (pinned to 4d089f9550)

Solutions

1. Run gum table in an interactive terminal session
2. Check that the parent context isn't cancelled before the program starts
3. Verify the environment exposes a usable TTY (not a stripped CI runner)
4. Inspect the wrapped cause (%w) for the specific tea failure and address it

Example fix

// before
CI_JOB=1 ./script.sh  # gum table fails: no TTY
// after
if [ -t 0 ]; then ./script.sh; else gum table < data.csv --no-input 2>/dev/null || true; fi

[ -t 0 ] && [ -t 2 ] || { echo 'gum table requires a TTY'; exit 1; }

if ! sel=$(gum table < data.csv 2>/dev/null); then
  echo 'selection cancelled or TUI failed' >&2
  exit 1
fi

When it happens

Trigger: `tea.NewProgram(...).Run()` returns an error: terminal not TTY-capable, context cancelled before program starts, or output initialization to os.Stderr fails.

Common situations: Running gum table in CI/non-interactive shells without a TTY, cancelling the command (Ctrl-C with context propagation or parent killed), restricted environments where /dev/tty is unavailable.

Related errors

• unable to start program: %w
• failed to run write: %w
• unable to run filter: %w
• unable to run action: %w
• failed to get selection

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