{"record":{"id":"cffa71b861a93aac","repo":"hasura/graphql-engine","slug":"unable-to-create-directory-w","errorCode":null,"errorMessage":"unable to create directory: %w","messagePattern":"unable to create directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/commands/docs.go","lineNumber":45,"sourceCode":"func NewDocsCmd(ec *cli.ExecutionContext) *cobra.Command {\n\tvar docType, docDirectory string\n\n\tdocsCmd := &cobra.Command{\n\t\tUse:          \"docs\",\n\t\tShort:        \"Generate CLI docs in various formats\",\n\t\tHidden:       true,\n\t\tSilenceUsage: true,\n\t\tPreRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\tec.Viper = viper.New()\n\n\t\t\treturn nil\n\t\t},\n\t\tRunE: func(cmd *cobra.Command, args []string) (err error) {\n\t\t\top := genOpName(cmd, \"RunE\")\n\n\t\t\terr = os.MkdirAll(docDirectory, os.ModePerm)\n\t\t\tif err != nil {\n\t\t\t\treturn errors.E(op, fmt.Errorf(\"unable to create directory: %w\", err))\n\t\t\t}\n\n\t\t\tswitch docType {\n\t\t\tcase \"man\":\n\t\t\t\terr = doc.GenManTree(\n\t\t\t\t\trootCmd,\n\t\t\t\t\t&doc.GenManHeader{Title: \"HASURA\", Section: \"3\"},\n\t\t\t\t\tdocDirectory,\n\t\t\t\t)\n\t\t\tcase \"mdx\":\n\t\t\t\tgenerateSidebarPositions(rootCmd)\n\t\t\t\terr = genMarkdownXTreeCustom(\n\t\t\t\t\trootCmd,\n\t\t\t\t\tdocDirectory,\n\t\t\t\t\tfunc(s string) string { return \"\" },\n\t\t\t\t\tfunc(s string) string { return fmt.Sprintf(\"%s%s\", rootPath, strings.ReplaceAll(s, \" \", \"_\")) },\n\t\t\t\t)\n\t\t\tcase \"md\":","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/commands/docs.go#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Choose a writable output directory (e.g. under $HOME or a project dir)","If a path component exists as a regular file, remove or rename it and retry","Fix directory permissions or run in a writable location (volume-mounted dir in containers)"],"exampleFix":"// before\ndocs --directory /usr/share/hasura-docs\n// after\ndocs --directory ~/hasura-docs","handlingStrategy":"validation","validationCode":"if info, err := os.Stat(outDir); err == nil && !info.IsDir() {\n    log.Fatal(\"output path is a file, not a directory\")\n}\nif err := os.MkdirAll(outDir, 0o755); err != nil { log.Fatal(err) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Generate docs into user-writable directories","Avoid root-owned system paths without permissions"],"tags":["hasura","cli","docs","mkdir","filesystem"],"backgroundTag":"directory-create-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}