{"record":{"id":"69c853a89ebde244","repo":"gohugoio/hugo","slug":"failled-to-create-base-cache-directory-s","errorCode":null,"errorMessage":"failled to create base cache directory: %s","messagePattern":"failled to create base cache directory: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cache/filecache/filecache.go","lineNumber":111,"sourceCode":"\tafero.File\n\tunlock func()\n}\n\nfunc (l *lockedFile) Close() error {\n\tdefer l.unlock()\n\treturn l.File.Close()\n}\n\nfunc (c *Cache) init() error {\n\tif c == nil {\n\t\tpanic(\"cache is nil\")\n\t}\n\n\tc.initOnce.Do(func() {\n\t\tc.isInited = true\n\t\t// Create the base dir if it does not exist.\n\t\tif err := c.Fs.MkdirAll(\"\", 0o777); err != nil && !os.IsExist(err) {\n\t\t\terr = fmt.Errorf(\"failled to create base cache directory: %s\", err)\n\t\t\tc.initErr = err\n\t\t}\n\t})\n\treturn c.initErr\n}\n\n// WriteCloser returns a transactional writer into the cache.\n// It's important that it's closed when done.\nfunc (c *Cache) WriteCloser(id string) (ItemInfo, io.WriteCloser, error) {\n\tif err := c.init(); err != nil {\n\t\treturn ItemInfo{}, nil, err\n\t}\n\n\tid = cleanID(id)\n\tc.entryLocker.Lock(id)\n\n\tinfo := ItemInfo{Name: id}\n","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/cache/filecache/filecache.go#L93-L129","documentation":"During lazy file-cache initialization, Cache.init calls c.Fs.MkdirAll(\"\", 0o777) to create the cache base directory (filecache.go:110). If MkdirAll fails with a non-existence-ignorable error, it is stored as initErr and returned on every subsequent cache operation. Note the message contains a typo ('failled').","triggerScenarios":"The resolved cache filesystem path is read-only, lacks write/execute permissions, or the path is invalid for directory creation.","commonSituations":"Running Hugo as a user lacking write permission to the cache dir; read-only container/CI filesystem; cacheDir pointing to a read-only mounted volume; disk quota exceeded.","solutions":["Check and fix write permissions on the configured cacheDir","Set cacheDir to a writable location via --cacheDir flag or cacheDir in config","If running in a container, ensure the cache volume is mounted writable"],"exampleFix":"# before: read-only cache dir\nhugo --cacheDir /opt/hugo-cache\n# after: writable cache dir\nhugo --cacheDir /tmp/hugo-cache","handlingStrategy":"validation","validationCode":"// Verify the cache dir is writable before starting Hugo.\nfunc checkCacheDirWritable(dir string) error {\n    info, err := os.Stat(dir)\n    if os.IsNotExist(err) {\n        return os.MkdirAll(dir, 0o755)\n    }\n    if err != nil {\n        return err\n    }\n    if !info.IsDir() {\n        return fmt.Errorf(\"%s is not a directory\", dir)\n    }\n    return os.WriteFile(filepath.Join(dir, \".write_test\"), []byte(\"x\"), 0o644)\n}","typeGuard":null,"tryCatchPattern":"// The init error surfaces on the first cache operation; check it early.\nif err := cache.GetOrCreate(...); err != nil {\n    if strings.Contains(err.Error(), \"create base cache directory\") {\n        log.Fatal(\"fix cache dir permissions: \", err)\n    }\n}","preventionTips":["Set --cacheDir to a known-writable absolute path in CI","Ensure the cache directory is owned by the Hugo process user","Mount container cache volumes as writable"],"tags":["cache","filecache","filesystem","permissions","initialization","hugo"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}