designated output directory and specified section are requir

Error message

designated output directory and specified section are required

What it means

From the hidden 'manpage' command: the --directory/-o flag is required to know where to emit the generated man pages, and it was empty or whitespace after trimming. Section is hardcoded to 8, so only the directory is actually user-supplied.

Source

Thrown at cmd/commands.go:470

	defaultFactory.Use(func(rootCmd *cobra.Command) {
		manpageCommand := Command{
			Name:  "manpage",
			Usage: "--directory <path>",
			Short: "Generates the manual pages for Caddy commands",
			Long: `
Generates the manual pages for Caddy commands into the designated directory
tagged into section 8 (System Administration).

The manual page files are generated into the directory specified by the
argument of --directory. If the directory does not exist, it will be created.
`,
			CobraFunc: func(cmd *cobra.Command) {
				cmd.Flags().StringP("directory", "o", "", "The output directory where the manpages are generated")
				cmd.RunE = WrapCommandFuncForCobra(func(fl Flags) (int, error) {
					dir := strings.TrimSpace(fl.String("directory"))
					if dir == "" {
						return caddy.ExitCodeFailedQuit, fmt.Errorf("designated output directory and specified section are required")
					}
					if err := os.MkdirAll(dir, 0o755); err != nil {
						return caddy.ExitCodeFailedQuit, err
					}
					if err := doc.GenManTree(rootCmd, &doc.GenManHeader{
						Title:   "Caddy",
						Section: "8", // https://en.wikipedia.org/wiki/Man_page#Manual_sections
					}, dir); err != nil {
						return caddy.ExitCodeFailedQuit, err
					}
					return caddy.ExitCodeSuccess, nil
				})
			},
		}

		// source: https://github.com/spf13/cobra/blob/6dec1ae26659a130bdb4c985768d1853b0e1bc06/site/content/completions/_index.md
		completionCommand := Command{
			Name:  "completion",

View on GitHub (pinned to 50e54ee279)

Solutions

Pass an explicit output directory: caddy manpage --directory /usr/local/share/man/man8
In scripts, fail fast if the directory variable is empty before calling the command

Example fix

# before
caddy manpage

# after
caddy manpage --directory /tmp/caddy-man

Defensive patterns

Strategy: validation

Validate before calling

# Fail fast in scripts when the target directory is unset:
: "${MAN_DIR:?MAN_DIR must be set}"
caddy manpage --directory "$MAN_DIR"

Prevention

Treat --directory as mandatory in packaging scripts
Shell parameter expansion with :? catches empty vars before the CLI does

When it happens

Trigger: Running 'caddy manpage' without -o, or with -o " " (whitespace-only).

Common situations: Packaging scripts invoking 'caddy manpage' and expecting files in the CWD; users assuming a default output directory exists.

Related errors

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/a01005799b32ca14. Report an issue: GitHub.