What causes "unable to write output: %w" in charmbracelet/gum?

Check whether the consumer of the pipe exited early (EPIPE); avoid `head`/`grep -q` short-circuits or ignore SIGPIPE.

unable to write output: %w

Error message

unable to write output: %w

What it means

gum format renders markdown/code/emoji/text and then writes the result with `fmt.Fprint(tty.Writer(), output)`. If that final write fails, Run wraps the error as `unable to write output: %w`. The rendering succeeded; only the emission to the TTY writer failed.

Source

Thrown at format/command.go:46

		input, _ = stdin.Read(stdin.StripANSI(o.StripANSI))
	}

	switch o.Type {
	case "code":
		output, err = code(input, o.Language)
	case "emoji":
		output, err = emoji(input)
	case "template":
		output, err = template(input)
	default:
		output, err = markdown(input, o.Theme)
	}
	if err != nil {
		return err
	}

	if _, err := fmt.Fprint(tty.Writer(), output); err != nil {
		return fmt.Errorf("unable to write output: %w", err)
	}
	return nil
}

View on GitHub (pinned to 4d089f9550)

Solutions

Check whether the consumer of the pipe exited early (EPIPE); avoid `head`/`grep -q` short-circuits or ignore SIGPIPE.
Verify disk space and write permissions on the redirect target.
Run `gum format` writing to a healthy terminal or a writable file.
Inspect the wrapped error (`EPIPE`, `ENOSPC`) to pinpoint the cause.

Example fix

// before
gum format -t markdown "$doc" | head -1 // consumer exits -> broken pipe
// after
gum format -t markdown "$doc" | sed -n '1p;q' # or capture full output first: out=$(gum format -t markdown "$doc")

Defensive patterns

Strategy: try-catch

Try / catch

if ! out=$(gum format -t markdown "$doc"); then
  echo "write failed: $out (EPIPE? ENOSPC?)" >&2
fi

Prevention

Avoid pipe consumers that exit early (head) or tolerate SIGPIPE.
Check disk space before writing large formatted output to files.
Capture output into a variable instead of chaining fragile pipes.
Inspect the wrapped errno (EPIPE/ENOSPC/EBADF) to diagnose quickly.

When it happens

Trigger: The writer returned by the TTY detection (`tty.Writer()`) points at a closed or broken descriptor — e.g. stdout piped to a process that exited (EPIPE), a full disk, or an invalid output target.

Common situations: `gum format ... | head -1` closing the pipe early (broken pipe); redirecting output to a file on a full filesystem; output device removed/disconnected mid-run.

Related errors

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