{"record":{"id":"fabc6cf9be19c35f","repo":"gohugoio/hugo","slug":"fatal-filecache-error","errorCode":null,"errorMessage":"fatal filecache error","messagePattern":"fatal filecache error","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cache/filecache/filecache.go","lineNumber":39,"sourceCode":"\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/gohugoio/httpcache\"\n\t\"github.com/gohugoio/hugo/common/hugio\"\n\t\"github.com/gohugoio/hugo/hugofs\"\n\n\t\"github.com/gohugoio/hugo/helpers\"\n\n\t\"github.com/BurntSushi/locker\"\n\t\"github.com/bep/helpers/maphelpers\"\n\t\"github.com/spf13/afero\"\n)\n\n// ErrFatal can be used to signal an unrecoverable error.\nvar ErrFatal = errors.New(\"fatal filecache error\")\n\nconst (\n\tFilecacheRootDirname = \"filecache\"\n)\n\n// Cache caches a set of files in a directory. This is usually a file on\n// disk, but since this is backed by an Afero file system, it can be anything.\ntype Cache struct {\n\tFs afero.Fs\n\n\tcfg FileCacheConfig\n\n\tentryLocker *lockTracker\n\n\tinitOnce sync.Once\n\tisInited bool\n\tinitErr  error\n}","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/cache/filecache/filecache.go#L21-L57","documentation":"ErrFatal is a sentinel declared in the filecache package and used by ReadOrCreate (filecache.go:164) to distinguish a deliberate, unrecoverable cache failure from ordinary errors. When a read callback returns ErrFatal, ReadOrCreate stops treating it as a cache-miss-and-recreate recovery and propagates the error.","triggerScenarios":"A cache read callback returns filecache.ErrFatal to signal corruption or an unrecoverable condition; the value is compared via errors.Is in the ReadOrCreate flow.","commonSituations":"A resource decoder detects unrecoverable corruption; disk or cache filesystem failure; a downstream package reuses ErrFatal to halt the build.","solutions":["Clear the affected cache directory (e.g. remove the filecache dir) and rebuild","Investigate the callback that returned ErrFatal for the real underlying cause","Ensure the cache directory is writable and on healthy storage"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isFatalFilecacheErr(err error) bool { return errors.Is(err, filecache.ErrFatal) }","tryCatchPattern":"if _, err := cache.ReadOrCreate(id, readFn, createFn); err != nil {\n    if errors.Is(err, filecache.ErrFatal) {\n        // unrecoverable: surface to user, do not retry\n    } else {\n        // transient: handle or retry\n    }\n}","preventionTips":["Treat ErrFatal as non-retryable; never mask it with a generic retry loop","Periodically clear stale cache directories to avoid corruption buildup"],"tags":["filecache","cache","go","sentinel"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}