hasura/graphql-engine · error

unable to create directory: %w

Error message

unable to create directory: %w

What it means

Thrown by the docs generation command when os.MkdirAll cannot create the output directory for generated CLI documentation (man pages/yaml/markdown). The CLI docs command creates the target directory with full permissions before generating docs into it.

Source

Thrown at cli/commands/docs.go:45

func NewDocsCmd(ec *cli.ExecutionContext) *cobra.Command {
	var docType, docDirectory string

	docsCmd := &cobra.Command{
		Use:          "docs",
		Short:        "Generate CLI docs in various formats",
		Hidden:       true,
		SilenceUsage: true,
		PreRunE: func(cmd *cobra.Command, args []string) error {
			ec.Viper = viper.New()

			return nil
		},
		RunE: func(cmd *cobra.Command, args []string) (err error) {
			op := genOpName(cmd, "RunE")

			err = os.MkdirAll(docDirectory, os.ModePerm)
			if err != nil {
				return errors.E(op, fmt.Errorf("unable to create directory: %w", err))
			}

			switch docType {
			case "man":
				err = doc.GenManTree(
					rootCmd,
					&doc.GenManHeader{Title: "HASURA", Section: "3"},
					docDirectory,
				)
			case "mdx":
				generateSidebarPositions(rootCmd)
				err = genMarkdownXTreeCustom(
					rootCmd,
					docDirectory,
					func(s string) string { return "" },
					func(s string) string { return fmt.Sprintf("%s%s", rootPath, strings.ReplaceAll(s, " ", "_")) },
				)
			case "md":

View on GitHub (pinned to 724551b9ae)

Solutions

1. Choose a writable output directory (e.g. under $HOME or a project dir)
2. If a path component exists as a regular file, remove or rename it and retry
3. Fix directory permissions or run in a writable location (volume-mounted dir in containers)

Example fix

// before
docs --directory /usr/share/hasura-docs
// after
docs --directory ~/hasura-docs

if info, err := os.Stat(outDir); err == nil && !info.IsDir() {
    log.Fatal("output path is a file, not a directory")
}
if err := os.MkdirAll(outDir, 0o755); err != nil { log.Fatal(err) }

When it happens

Trigger: Running the docs generation command with an output path that cannot be created: permission denied on a parent directory, a path component that is a file (ENOTDIR), or read-only filesystem.

Common situations: Generating docs into /usr/share or another root-owned path without sudo; output path colliding with an existing file; container with read-only root filesystem.

Related errors

• generating docs failed: %w
• error creating setup directories: %w
• error getting current working directory: %w
• directory '%s' already exists
• cannot write migration directory: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/cffa71b861a93aac. Report an issue: GitHub.