{"id":"31b454742b2f9c3a","repo":"gohugoio/hugo","slug":"errfatal","errorCode":"ErrFatal","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/8a468df065a75c1c7cf9f6850f32148746590ea5/cache/filecache/filecache.go#L21-L57","documentation":"`filecache.ErrFatal` is a sentinel error (`errors.New(\"fatal filecache error\")`) used to signal an unrecoverable failure inside Hugo's file cache. Cache users wrap or compare against it so callers can distinguish 'retry/ignore' cache misses from failures that must abort the operation — e.g. a `resources/GetRemote` fetch callback failing in a way that shouldn't be cached or retried.","triggerScenarios":"A `ReadOrCreate`/`GetOrCreate` callback in the filecache signals an unrecoverable condition and the error chain matches `errors.Is(err, filecache.ErrFatal)` — for example remote resource fetching or dynacache-backed operations that hit a hard I/O or logic failure rather than a transient miss.","commonSituations":"Rarely seen directly by users; surfaces when the cache directory becomes unwritable mid-build, disk fills up, or an internal create callback fails hard — often on locked-down CI runners or read-only container filesystems where `cacheDir` isn't writable.","solutions":["Inspect the accompanying wrapped error text for the real cause (I/O failure, fetch failure) and fix that underlying condition.","Ensure the cache directory (config `cacheDir`, `HUGO_CACHEDIR`, or the OS default) is writable and has free space.","Clear a possibly corrupted cache with `hugo --gc` or by deleting the cache directory, then rebuild."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"# Ensure the cache dir is writable and not on a full disk:\ndf -h \"$(hugo config | grep -i cachedir | cut -d= -f2)\"","typeGuard":"// Hugo tags this ErrFatal; callers embedding Hugo can check:\nfunc isFatalCacheErr(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"fatal filecache error\")\n}","tryCatchPattern":"if err := build(); err != nil {\n    if isFatalCacheErr(err) {\n        // corrupt cache — clear and retry once\n        exec.Command(\"hugo\", \"--gc\").Run()\n    }\n    return err\n}","preventionTips":["Set cacheDir to a stable, writable, non-tmpfs location in CI","Clear the cache (hugo --gc or delete the cache dir) after Hugo version upgrades if fatal cache errors appear","Monitor disk space on the cache volume","Don't share one cache dir between concurrent Hugo processes"],"tags":["hugo","filecache","sentinel-error","io"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}