gohugoio/hugo · error
walk: Readdir: %w
Error message
walk: Readdir: %w
What it means
Once a directory is open, Walkway.walk calls ReadDirWithContext to list its entries. A failure reading the directory listing (other than a tolerated not-exist) is wrapped with %w as "walk: Readdir: ..." and aborts the walk. Because it uses %w, the underlying OS error remains inspectable by callers via errors.Is/As.
Source
Thrown at hugofs/walk.go:172
}
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()))
}
}
if w.cfg.SortDirEntries {
sort.Slice(dirEntries, func(i, j int) bool {
return dirEntries[i].Name() < dirEntries[j].Name()
})
}
}
if w.cfg.IgnoreFile != nil {View on GitHub ↗ (pinned to 8a468df065)
Solutions
- Inspect the wrapped OS error for the root cause (I/O error, stale handle) and check the health of the underlying storage.
- Move the project off cloud-sync placeholder folders or force files to be locally available before building.
- If it happens during watch rebuilds when directories are deleted, re-run the build; exclude tooling temp directories from content mounts.
Defensive patterns
Strategy: try-catch
Try / catch
err := w.Walk()
if err != nil {
// %w-wrapped: unwrap with errors.As(&pathErr) to get the failing directory
var pe *fs.PathError
if errors.As(err, &pe) { /* pe.Path names the unreadable dir */ }
} Prevention
- Same hygiene as open: readable directories, no mid-walk mutation, stable filesystem.
- Watch for directories that disappear between open and Readdir (temp dirs, editor swap dirs) — exclude them from mounts.
- This error wraps with %w, so use errors.Is/errors.As rather than string matching to classify it.
When it happens
Trigger: Readdir on an already-opened directory failing: I/O errors on the underlying storage, the directory being removed mid-listing, network filesystem hiccups (NFS/SMB), or errors surfaced by Hugo's composite/overlay filesystems while merging mount entries.
Common situations: Building from network shares or cloud-synced folders (Dropbox/OneDrive placeholders that fail on enumeration), flaky container volumes, or directories deleted by another process during `hugo server` watch rebuilds.
Related errors
- walk: stat: %s
- failed to walk archetype dir %q: %w
- failed to read archetype file: %w
- failed to open image for decode: %w
- %q is not a directory
AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31).
Data as JSON: /data/errors/f417297cb828b2ac.json.
Report an issue: GitHub ↗.