What causes "walk: open: path: %q filename: %q: %s" in gohugoio/hugo?

Check the `filename` in the message — that's the real on-disk path; fix its permissions or existence.

walk: open: path: %q filename: %q: %s

Error message

walk: open: path: %q filename: %q: %s

What it means

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.

Source

Thrown at hugofs/walk.go:162

	err := w.cfg.WalkFn(ctx, path, info)
	if err != nil {
		if info.IsDir() && err == filepath.SkipDir {
			return nil
		}
		return err
	}

	if !info.IsDir() {
		return nil
	}

	if dirEntries == nil {
		f, err := w.cfg.Fs.Open(path)
		if err != nil {
			if w.checkErr(path, err) {
				return nil
			}
			return fmt.Errorf("walk: open: path: %q filename: %q: %s", path, info.Meta().Filename, err)
		}
		fis, newCtx, err := ReadDirWithContext(ctx, f, -1)
		ctx = newCtx

		f.Close()
		if err != nil {
			if w.checkErr(path, err) {
				return nil
			}
			return fmt.Errorf("walk: Readdir: %w", err)
		}

		dirEntries = DirEntriesToFileMetaInfos(fis)
		for _, fi := range dirEntries {
			if fi.Meta().PathInfo == nil {
				fi.Meta().PathInfo = w.cfg.PathParser.Parse("", filepath.Join(pathRel, fi.Name()))
			}
		}

View on GitHub ↗ (pinned to 8a468df065)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

f, err := os.Open(dir)
if err == nil { f.Close() } else { /* fix permissions/path before walking */ }

Try / catch

err := w.Walk()
if err != nil {
	switch {
	case errors.Is(err, fs.ErrPermission): // fix directory exec/read bits
	case errors.Is(err, fs.ErrNotExist):   // directory removed mid-walk; re-scan
	default: // surface with the path/filename the error carries
	}
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/efe12a2caf662cf9.json. Report an issue: GitHub ↗.