hasura/graphql-engine · error

generating docs failed: %w

Error message

generating docs failed: %w

What it means

Wrapped error from the docs command when cobra's doc generator (GenManTree/GenMarkdownTree/GenYamlTree) fails while producing documentation files. The command supports man/markdown/yaml types; a failure after generation starts surfaces here.

Source

Thrown at cli/commands/docs.go:80

				)
			case "md":
				err = doc.GenMarkdownTree(rootCmd, docDirectory)
			case "rest":
				err = genReSTTreeCustom(
					rootCmd,
					docDirectory,
					"Hasura CLI: ",
					func(s string) string { return "" },
					sphinxLinkHandler,
				)
			case "yaml":
				err = doc.GenYamlTree(rootCmd, docDirectory)
			default:
				return errors.E(op, "unknown type")
			}

			if err != nil {
				return errors.E(op, fmt.Errorf("generating docs failed: %w", err))
			}

			ec.Logger.Infof("[%s] docs generated in [%s]", docType, docDirectory)

			return nil
		},
	}

	f := docsCmd.Flags()
	f.StringVar(
		&docType,
		"type",
		"md",
		"type of documentation to generate (man, md, mdx, rest, yaml)",
	)
	f.StringVar(&docDirectory, "directory", "docs", "directory where docs should be generated")

	return docsCmd

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the --type flag is one of man|markdown|yaml and re-run
2. Check disk space and write permissions in the output directory
3. Re-create the output directory and retry generation

switch docType {
case "man", "markdown", "yaml":
default:
    log.Fatalf("unsupported doc type: %s", docType)
}

if err := docsRun(); err != nil {
    if strings.Contains(err.Error(), "generating docs failed") { /* disk/permission issue */ }
}

When it happens

Trigger: Running docs generation where writing individual doc files fails: disk full, files become read-only mid-run, invalid output directory state, or an unrecognized doc type was supplied (default branch returns 'unknown type' separately).

Common situations: Disk quota exhausted during generation; output dir on a failing mount; passing an unsupported --type flag value leading to inconsistent state.

Related errors

• unable to create directory: %w
• error getting current working directory: %w
• directory '%s' already exists
• error creating setup directories: %w
• failed to create seed file: %w

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