{"record":{"id":"596638430510b0e0","repo":"gohugoio/hugo","slug":"failed-to-acquire-a-build-lock-s","errorCode":null,"errorMessage":"failed to acquire a build lock: %s","messagePattern":"failed to acquire a build lock: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"create/content.go","lineNumber":87,"sourceCode":"\t\tsourceFs:    h.PathSpec.Fs.Source,\n\t\tps:          h.PathSpec,\n\t\th:           h,\n\t\tcf:          cf,\n\n\t\tkind:       kind,\n\t\ttargetPath: targetPath,\n\t\tforce:      force,\n\t}\n\n\text := paths.Ext(targetPath)\n\n\tb.setArcheTypeFilenameToUse(ext)\n\n\twithBuildLock := func() (string, error) {\n\t\tif !h.Configs.Base.NoBuildLock {\n\t\t\tunlock, err := h.BaseFs.LockBuild()\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", fmt.Errorf(\"failed to acquire a build lock: %s\", err)\n\t\t\t}\n\t\t\tdefer unlock()\n\t\t}\n\n\t\tif b.isDir {\n\t\t\treturn \"\", b.buildDir()\n\t\t}\n\n\t\tif ext == \"\" {\n\t\t\treturn \"\", fmt.Errorf(\"failed to resolve %q to an archetype template\", targetPath)\n\t\t}\n\n\t\tif !h.Conf.ContentTypes().IsContentFile(b.targetPath) {\n\t\t\treturn \"\", fmt.Errorf(\"target path %q is not a known content format\", b.targetPath)\n\t\t}\n\n\t\treturn b.buildFile()\n\t}","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/create/content.go#L69-L105","documentation":"create.NewContent wraps its work in a build lock (create/content.go:85 -> BaseFs.LockBuild). The lock is a file lock at <project>/.hugo_build.lock (lockedfile.MutexAt, basefs.go:489). This wraps any failure to acquire that file lock. It is skipped only when Configs.Base.NoBuildLock is set.","triggerScenarios":"Another Hugo process (hugo server / hugo build / another hugo new) currently holds .hugo_build.lock; the project working dir or the lock file is not writable; a previously killed process left an OS-level lock; running on a read-only filesystem/container mount.","commonSituations":"Running `hugo new` concurrently with `hugo server`; CI running on a read-only checkout; stale lock after kill -9; lock file owned by another user.","solutions":["Ensure no other Hugo process is running against the same project (ps/pgrep for hugo).","Verify write permission on the project root and on .hugo_build.lock; chmod/chown if needed.","Remove a stale .hugo_build.lock file if no Hugo process is actually running.","If locking is unnecessary for your workflow, set noBuildLock in the base config to disable it."],"exampleFix":"# before: two concurrent processes fight over the lock\n$ hugo server &\n$ hugo new posts/x.md   # -> failed to acquire a build lock\n\n# after: stop the server first (or set noBuildLock)\n$ hugo new posts/x.md   # succeeds once the lock is free","handlingStrategy":"retry","validationCode":"// Check the lock file is writable before attempting NewContent.\nfunc CheckBuildLockWritable(workDir string) error {\n    p := filepath.Join(workDir, \".hugo_build.lock\")\n    f, err := os.OpenFile(p, os.O_RDWR|os.O_CREATE, 0o644)\n    if err != nil {\n        return err\n    }\n    return f.Close()\n}","typeGuard":null,"tryCatchPattern":"// Retry briefly on lock contention; fail fast on permission errors.\nvar lastErr error\nfor i := 0; i < 3; i++ {\n    err := create.NewContent(h, kind, path, force)\n    if err == nil { return nil }\n    lastErr = err\n    if !strings.Contains(err.Error(), \"build lock\") { return err }\n    // back off via a timer/channel; do not spin\n}\nreturn lastErr","preventionTips":["Do not run multiple Hugo writers against one project concurrently.","Ensure the project root and .hugo_build.lock are writable by the Hugo user.","Clean up stale lock files after a crash.","Set noBuildLock for ephemeral/programmatic runs that do not need locking."],"tags":["filesystem","locking","concurrency"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}