charmbracelet/glow · error

unable to instantiate man page: %w

Error message

unable to instantiate man page: %w

What it means

Thrown by glow's hidden `man` subcommand (man_cmd.go:20-22), which turns the cobra command tree into a roff man page via muesli/mango-cobra's NewManPage(1, rootCmd). mango-cobra walks rootCmd's commands, flags, and examples to build mango metadata; the error return exists for failures while enumerating that tree. With the pinned mango-cobra v1.3.0 and a well-formed command tree, this path is defensive and effectively unreachable in normal operation.

Source

Thrown at man_cmd.go:22

	"fmt"
	"os"

	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

1. Align dependency versions: `go get -u github.com/muesli/mango-cobra github.com/spf13/cobra && go mod tidy`, then rebuild and re-run `glow man > glow.1`.
2. If invoked programmatically, ensure rootCmd is fully constructed (persistent flags and subcommands registered) before the man command executes.
3. If it reproduces with a healthy tree, preserve the wrapped %w chain and report upstream to muesli/mango-cobra including your cobra version.
4. In release scripts, generate to a file (`glow man > glow.1`) so stdout write problems can't be confused with instantiation failures.

// Verify the command tree before generating man pages.
if rootCmd == nil {
	return errors.New("root command is not initialized")
}
for _, c := range rootCmd.Commands() {
	if c == nil {
		return errors.New("nil subcommand in command tree")
	}
}
manPage, err := mcobra.NewManPage(1, rootCmd)

manPage, err := mcobra.NewManPage(1, rootCmd)
if err != nil {
	return fmt.Errorf("unable to instantiate man page: %w", err)
}

When it happens

Trigger: Executing `glow man` (or manCmd.RunE directly in tests) when rootCmd is nil or only partially initialized (e.g. persistent flags/subcommands not yet registered due to init-order changes); a cobra command in the tree whose flag definitions fail to enumerate; version skew after a major cobra upgrade (go.mod pins cobra v1.10.2) that breaks mango-cobra's flag-metadata assumptions.

Common situations: Maintainers regenerating man pages for packaging or release automation; CI jobs invoking the hidden man command inside a test harness where rootCmd wiring differs from the real binary; dependency bumps of cobra/mango-cobra without re-running `go mod tidy` and the man generation step.

Related errors

• unable to build man page: %w
• missing markdown source
• cannot use both pager and tui
• unable to set config file: %w
• unable to parse url: %w

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