gohugoio/hugo · critical

fatal filecache error

Error message

fatal filecache error

What it means

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.

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 52c9bd7908)

Solutions

1. Clear the affected cache directory (e.g. remove the filecache dir) and rebuild
2. Investigate the callback that returned ErrFatal for the real underlying cause
3. Ensure the cache directory is writable and on healthy storage

func isFatalFilecacheErr(err error) bool { return errors.Is(err, filecache.ErrFatal) }

if _, err := cache.ReadOrCreate(id, readFn, createFn); err != nil {
    if errors.Is(err, filecache.ErrFatal) {
        // unrecoverable: surface to user, do not retry
    } else {
        // transient: handle or retry
    }
}

When it happens

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

Common situations: A resource decoder detects unrecoverable corruption; disk or cache filesystem failure; a downstream package reuses ErrFatal to halt the build.

Related errors

• must provide cache Dir
• failled to create base cache directory: %s
• cache dir %q contains unresolved placeholders
• %q is not a valid cache name
• failed to decode filecache config: %w

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/fabc6cf9be19c35f. Report an issue: GitHub.