Your indexer's filepath.WalkDir stops at one unreadable directory and writes a partial manifest — how should the callback handle that error?

## The error parameter is a policy hook ```go type fs.WalkDirFunc func(path string, d fs.DirEntry, err error) error ``` That third parameter is not "an error the walk had"; it is the walk *asking you what to do*. The traversal has already decided it cannot go into that directory. Your return value decides whether that is fatal for the whole job. `filepath.WalkDir` passes a non-nil `err` in exactly two situations. **The root could not be stat'ed.** Before walking anything, the traversal stats `root`. If that fails, the callback is invoked once with `path` set to the root, `err` set to the failure, and **`d` set to nil**. That nil is a real production hazard: a callback whose first line is `if d.IsDir()` panics on a mistyped root path. Check `err` before you touch `d`. **A directory could not be read.** Here the callback is called **twice** for the same path. The first call happens before the read is attempted, with `err == nil` and a valid `d` — this is your chance to return `fs.SkipDir` and avoid the read entirely. If the read then fails, the callback is called again with the same path and `err` set to the failure. (If the read succeeds there is no second call.) Callbacks that count entries or append to a manifest keyed by path need to be aware of that second visit, or a rare double-count appears only for directories that fail. Note what is *not* on this list: a permission error on an individual file. The walk never opens files, so a file you cannot read is reported perfectly normally; the failure surfaces later, in your own code, when you try to open it. ## The three policies **Return the error.** The traversal stops immediately and `filepath.WalkDir` returns that error. Correct when any gap invalidates the result — a backup or a checksum over the whole tree. **Return nil.** The walk continues with the next sibling; the unreadable directory's contents are simply absent. Correct when the tree is expected to be imperfect, but only if you *record* the fact somewhere. **Return `fs.SkipDir`.** Equivalent to nil in the failure case, since the walk was not going to descend anyway. It reads more clearly on the first, `err == nil` call when you are pruning deliberately. ## Classify, do not blanket-tolerate Blanket `return nil` is the mirror-image defect of blanket `return err`: it converts every failure, including a broken mount or a root that does not exist, into a quietly smaller output. Classify with `errors.Is`: ```go if err != nil { switch { case errors.Is(err, fs.ErrPermission): skipped = append(skipped, path) return nil case errors.Is(err, fs.ErrNotExist): // vanished between the parent's read and this visit; normal on a live tree return nil default: return fmt.Errorf("walking %s: %w", path, err) } } ``` `fs.ErrNotExist` deserves special mention. A directory listing is a snapshot; on a tree another process is writing to, entries disappear between the parent's read and the visit. Treating that as fatal makes an indexer that fails randomly under load, and it is exactly the kind of bug that never reproduces on a developer's quiet checkout. ## The output is the real question The interesting part of this scenario is not the callback — it is what happens downstream. A walk that tolerated errors produced a manifest that is *structurally valid and semantically incomplete*, and nothing about its shape says so. Whatever consumes it will treat missing assets as deleted assets. So the tolerant callback comes with an obligation: * Keep a count and a sample of skipped paths, and put them in the manifest itself or in the job's result, not only in a log line. * Decide a threshold. Zero skips: publish. A handful of known-unreadable directories: publish with the skip list recorded. Anything beyond that: fail the job rather than replace a good manifest with a lossy one. * Emit the skipped count as a metric, because the interesting failure is a slow drift upward, not a single bad run. "Fail closed on a partial result that replaces a known-good one" is the judgment being tested here. The API question — which parameter, called how many times — is the entry ticket. ## The shape to write ```go var skipped int err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { if err != nil { if errors.Is(err, fs.ErrPermission) { skipped++ return nil } return err } // ... record the entry return nil }) ``` Every `err != nil` branch is checked before `d` is touched, tolerance is narrow and named, and the count leaves the closure so the caller can refuse to publish.