gohugoio/hugo · critical

ErrFatal

ErrFatal

Error message

fatal filecache error

What it means

`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.

Source

Thrown at cache/filecache/filecache.go:39

	"os"
	"path/filepath"
	"strings"
	"sync"
	"time"

	"github.com/gohugoio/httpcache"
	"github.com/gohugoio/hugo/common/hugio"
	"github.com/gohugoio/hugo/hugofs"

	"github.com/gohugoio/hugo/helpers"

	"github.com/BurntSushi/locker"
	"github.com/bep/helpers/maphelpers"
	"github.com/spf13/afero"
)

// ErrFatal can be used to signal an unrecoverable error.
var ErrFatal = errors.New("fatal filecache error")

const (
	FilecacheRootDirname = "filecache"
)

// Cache caches a set of files in a directory. This is usually a file on
// disk, but since this is backed by an Afero file system, it can be anything.
type Cache struct {
	Fs afero.Fs

	cfg FileCacheConfig

	entryLocker *lockTracker

	initOnce sync.Once
	isInited bool
	initErr  error
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Inspect the accompanying wrapped error text for the real cause (I/O failure, fetch failure) and fix that underlying condition.
2. Ensure the cache directory (config `cacheDir`, `HUGO_CACHEDIR`, or the OS default) is writable and has free space.
3. Clear a possibly corrupted cache with `hugo --gc` or by deleting the cache directory, then rebuild.

# Ensure the cache dir is writable and not on a full disk:
df -h "$(hugo config | grep -i cachedir | cut -d= -f2)"

// Hugo tags this ErrFatal; callers embedding Hugo can check:
func isFatalCacheErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "fatal filecache error")
}

if err := build(); err != nil {
    if isFatalCacheErr(err) {
        // corrupt cache — clear and retry once
        exec.Command("hugo", "--gc").Run()
    }
    return err
}

When it happens

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

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

Related errors

• errHelp
• failed to create file caches from configuration: %w
• failed to read archetype file: %w
• failed to open image for decode: %w
• failed to read remote resource %q: %w

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