What causes "unable to build man page: %w" in charmbracelet/glow?

Write to a file instead of a short-lived pipe: `glow man > glow.1`.

unable to build man page: %w

Error message

unable to build man page: %w

What it means

Despite the message, this does not come from manPage.Build() — Build returns a plain string and cannot fail. The wrapped error is from fmt.Fprint(os.Stdout, ...) at man_cmd.go:24: a write failure on standard output. Typical causes are EPIPE (the downstream reader exited early), ENOSPC (redirect target disk full), or EBADF (file descriptor 1 closed).

Source

Thrown at man_cmd.go:25

	mcobra "github.com/muesli/mango-cobra"
	"github.com/muesli/roff"
	"github.com/spf13/cobra"
)

var manCmd = &cobra.Command{
	Use:                   "man",
	Short:                 "Generates manpages",
	SilenceUsage:          true,
	DisableFlagsInUseLine: true,
	Hidden:                true,
	Args:                  cobra.NoArgs,
	RunE: func(*cobra.Command, []string) error {
		manPage, err := mcobra.NewManPage(1, rootCmd)
		if err != nil {
			return fmt.Errorf("unable to instantiate man page: %w", err)
		}
		if _, err := fmt.Fprint(os.Stdout, manPage.Build(roff.NewDocument())); err != nil {
			return fmt.Errorf("unable to build man page: %w", err)
		}
		return nil
	},
}

View on GitHub (pinned to e3970c813d)

Solutions

Write to a file instead of a short-lived pipe: `glow man > glow.1`.
Avoid early-exiting pipe consumers; use a pager that reads everything (`glow man | less`) rather than `head`.
If wrapping the command, treat EPIPE as success before failing (see typeGuard/tryCatchPattern).
Check disk space and fd wiring of the environment when the error persists without pipes.

Example fix

# before: pipe closes early -> unable to build man page: ... broken pipe
glow man | head -n 1

# after: write to a file, or consume the whole stream
glow man > glow.1
glow man | less

Defensive patterns

Strategy: try-catch

Type guard

func isEPIPE(err error) bool {
	return errors.Is(err, syscall.EPIPE)
}

Try / catch

if _, err := fmt.Fprint(os.Stdout, manPage.Build(roff.NewDocument())); err != nil {
	if errors.Is(err, syscall.EPIPE) {
		return nil // reader closed the pipe early; output already delivered
	}
	return fmt.Errorf("unable to build man page: %w", err)
}

Prevention

Redirect generator output to a file instead of piping (`glow man > glow.1`).
Never pipe bulk generators into early-exiting consumers like `head -n 1` or `grep -m1`.
Ensure the downstream process reads the entire stream before exiting.
In CI, verify free disk space before redirecting man page output.

When it happens

Trigger: `glow man | head -n 5` — head exits after the first write, the pipe closes, and the next write returns EPIPE; redirecting to a full filesystem (`glow man > /tmp/glow.1` with no space); running under a supervisor that closed stdout (`glow man >&-`); piping into any consumer that stops reading mid-stream.

Common situations: Shell piping while generating docs; CI artifacts on disk-constrained runners; goreleaser-style man page generation scripts; debugging sessions where output is piped to `head`/`grep -m1`.

Related errors

AI-assisted analysis of charmbracelet/glow@e3970c813d (2026-08-15). Data as JSON: /api/errors/fa789d86cfdad138. Report an issue: GitHub.