gohugoio/hugo · error

failed to create cache dir

Error message

failed to create cache dir: %w

What it means

helpers.GetCacheDir (helpers/path.go:251) MkdirAll's the configured cacheDir (0o777 before umask) when it does not yet exist. This wraps the MkdirAll failure. The cacheDir comes from the cacheDir base setting or the --cacheDir flag.

Solutions

1. Point cacheDir at a writable location (set cacheDir in config or pass --cacheDir).
2. Fix permissions on the cacheDir path and its parents (chmod/chown).
3. Free disk space / inodes on the target volume.
4. Let Hugo fall back to the user cache dir by leaving cacheDir unset on a writable home.

Example fix

# before: cacheDir on a read-only mount
$ hugo --cacheDir /opt/hugo-cache   # /opt is read-only

# after
$ hugo --cacheDir /tmp/hugo-cache

// Confirm the cacheDir is creatable before Hugo starts.
func ValidateCacheDir(fs afero.Fs, cacheDir string) error {
    exists, err := helpers.DirExists(cacheDir, fs)
    if err != nil { return err }
    if exists { return nil }
    return fs.MkdirAll(cacheDir, 0o777)
}

if _, err := helpers.GetCacheDir(fs, cacheDir); err != nil {
    return err
}

When it happens

Trigger: The configured cacheDir points to a path that cannot be created: permission denied on a parent, read-only filesystem, disk/inode full, or an otherwise invalid path.

Common situations: CI on a read-only checkout; cacheDir on a volume the Hugo user cannot write to; full disk/tmpfs; cacheDir with a nonexistent user home.

Related errors

• failed to copy config dir to vendor dir
• failed to copy module file to vendor
• failed to copy module to vendor dir
• failed to copy to
• failed to copy resources to vendor dir

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

Appendix: source

Thrown at helpers/path.go:253

	}

	return f, err
}

// GetCacheDir returns a cache dir from the given filesystem and config.
// The dir will be created if it does not exist.
func GetCacheDir(fs afero.Fs, cacheDir string) (string, error) {
	cacheDir = cacheDirDefault(cacheDir)

	if cacheDir != "" {
		exists, err := DirExists(cacheDir, fs)
		if err != nil {
			return "", err
		}
		if !exists {
			err := fs.MkdirAll(cacheDir, 0o777) // Before umask
			if err != nil {
				return "", fmt.Errorf("failed to create cache dir: %w", err)
			}
		}
		return cacheDir, nil
	}

	const hugoCacheBase = "hugo_cache"

	// Avoid filling up the home dir with Hugo cache dirs from development.
	if !htesting.IsTest {
		userCacheDir, err := os.UserCacheDir()
		if err == nil {
			cacheDir := filepath.Join(userCacheDir, hugoCacheBase)
			if err := fs.Mkdir(cacheDir, 0o777); err == nil || os.IsExist(err) {
				return cacheDir, nil
			}
		}
	}

View on GitHub (pinned to 52c9bd7908)