{"id":"efe12a2caf662cf9","repo":"gohugoio/hugo","slug":"walk-open-path-q-filename-q-s","errorCode":null,"errorMessage":"walk: open: path: %q filename: %q: %s","messagePattern":"walk: open: path: %q filename: %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugofs/walk.go","lineNumber":162,"sourceCode":"\terr := w.cfg.WalkFn(ctx, path, info)\n\tif err != nil {\n\t\tif info.IsDir() && err == filepath.SkipDir {\n\t\t\treturn nil\n\t\t}\n\t\treturn err\n\t}\n\n\tif !info.IsDir() {\n\t\treturn nil\n\t}\n\n\tif dirEntries == nil {\n\t\tf, err := w.cfg.Fs.Open(path)\n\t\tif err != nil {\n\t\t\tif w.checkErr(path, err) {\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\treturn fmt.Errorf(\"walk: open: path: %q filename: %q: %s\", path, info.Meta().Filename, err)\n\t\t}\n\t\tfis, newCtx, err := ReadDirWithContext(ctx, f, -1)\n\t\tctx = newCtx\n\n\t\tf.Close()\n\t\tif err != nil {\n\t\t\tif w.checkErr(path, err) {\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\treturn fmt.Errorf(\"walk: Readdir: %w\", err)\n\t\t}\n\n\t\tdirEntries = DirEntriesToFileMetaInfos(fis)\n\t\tfor _, fi := range dirEntries {\n\t\t\tif fi.Meta().PathInfo == nil {\n\t\t\t\tfi.Meta().PathInfo = w.cfg.PathParser.Parse(\"\", filepath.Join(pathRel, fi.Name()))\n\t\t\t}\n\t\t}","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugofs/walk.go#L144-L180","documentation":"After statting a directory, Walkway.walk opens it to enumerate entries. If Fs.Open fails with an error that isn't a tolerated not-exist, it returns this error including both the virtual path and the underlying real filename from the file's metadata, which helps map a virtual-filesystem path (module mounts, theme overlays) back to the on-disk file that failed.","triggerScenarios":"Fs.Open on a directory failing during the walk: permission denied on the directory, too many open files (EMFILE/ulimit), the directory being deleted between Stat and Open, or errors from an overlay/module-mounted filesystem.","commonSituations":"CI containers or shared hosts with restrictive directory permissions on mounted themes/modules, very large sites hitting file-descriptor limits, antivirus/sync tools locking directories on Windows, and module mounts pointing at directories the build user cannot open.","solutions":["Check the `filename` in the message — that's the real on-disk path; fix its permissions or existence.","If the error is 'too many open files', raise the ulimit (`ulimit -n`) or reduce concurrent watchers.","Verify module mounts in the config point at readable directories."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"f, err := os.Open(dir)\nif err == nil { f.Close() } else { /* fix permissions/path before walking */ }","typeGuard":null,"tryCatchPattern":"err := w.Walk()\nif err != nil {\n\tswitch {\n\tcase errors.Is(err, fs.ErrPermission): // fix directory exec/read bits\n\tcase errors.Is(err, fs.ErrNotExist):   // directory removed mid-walk; re-scan\n\tdefault: // surface with the path/filename the error carries\n\t}\n}","preventionTips":["Ensure the process has read+execute permission on every directory under the walked roots.","Avoid deleting or renaming directories while a build/walk is running (watch mode races).","On network/virtual filesystems, expect transient open failures and treat them as fatal build errors, not data to skip."],"tags":["hugo","filesystem","walk","permissions","module-mounts"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}