{"record":{"id":"7cebbb4c17ed225d","repo":"charmbracelet/glow","slug":"unable-to-instantiate-man-page-w","errorCode":null,"errorMessage":"unable to instantiate man page: %w","messagePattern":"unable to instantiate man page: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"man_cmd.go","lineNumber":22,"sourceCode":"\t\"fmt\"\n\t\"os\"\n\n\tmcobra \"github.com/muesli/mango-cobra\"\n\t\"github.com/muesli/roff\"\n\t\"github.com/spf13/cobra\"\n)\n\nvar manCmd = &cobra.Command{\n\tUse:                   \"man\",\n\tShort:                 \"Generates manpages\",\n\tSilenceUsage:          true,\n\tDisableFlagsInUseLine: true,\n\tHidden:                true,\n\tArgs:                  cobra.NoArgs,\n\tRunE: func(*cobra.Command, []string) error {\n\t\tmanPage, err := mcobra.NewManPage(1, rootCmd)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"unable to instantiate man page: %w\", err)\n\t\t}\n\t\tif _, err := fmt.Fprint(os.Stdout, manPage.Build(roff.NewDocument())); err != nil {\n\t\t\treturn fmt.Errorf(\"unable to build man page: %w\", err)\n\t\t}\n\t\treturn nil\n\t},\n}\n","sourceCodeStart":4,"sourceCodeEnd":30,"githubUrl":"https://github.com/charmbracelet/glow/blob/e3970c813d93da1ea84edfca90c289d9afb82242/man_cmd.go#L4-L30","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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`.","If invoked programmatically, ensure rootCmd is fully constructed (persistent flags and subcommands registered) before the man command executes.","If it reproduces with a healthy tree, preserve the wrapped %w chain and report upstream to muesli/mango-cobra including your cobra version.","In release scripts, generate to a file (`glow man > glow.1`) so stdout write problems can't be confused with instantiation failures."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify the command tree before generating man pages.\nif rootCmd == nil {\n\treturn errors.New(\"root command is not initialized\")\n}\nfor _, c := range rootCmd.Commands() {\n\tif c == nil {\n\t\treturn errors.New(\"nil subcommand in command tree\")\n\t}\n}\nmanPage, err := mcobra.NewManPage(1, rootCmd)","typeGuard":null,"tryCatchPattern":"manPage, err := mcobra.NewManPage(1, rootCmd)\nif err != nil {\n\treturn fmt.Errorf(\"unable to instantiate man page: %w\", err)\n}","preventionTips":["Pin known-compatible cobra and mango-cobra versions in go.mod and update them together.","Exercise `glow man > glow.1` in CI so command-tree regressions surface at build time, not release time.","Keep the man command out of interactive flows; run it only in packaging/release automation."],"tags":["cli","cobra","man-pages","documentation-generation","go"],"backgroundTag":null,"analyzedSha":"e3970c813d93da1ea84edfca90c289d9afb82242","analyzedAt":"2026-08-15T22:50:54.304Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}