{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/create/content.go#L69-L105","documentation":"Before creating new content, Hugo takes the project's build lock (a .hugo_build.lock file) via h.BaseFs.LockBuild() so `hugo new` doesn't race a concurrently running build/server. This error means acquiring that file lock failed — the wrapped error explains why (timeout waiting on another holder, or a filesystem error creating the lock file).","triggerScenarios":"`hugo new content ...` while another Hugo process (e.g. `hugo server`) holds the lock long enough to time out; the lock file or project directory not writable; a stale lock on a filesystem where flock semantics are broken (some network mounts). Skipped entirely when `noBuildLock: true` is configured.","commonSituations":"Running `hugo new` while a long build is in progress; read-only project checkouts or CI workspaces; Docker/NFS/network volumes with unreliable file locking; leftover .hugo_build.lock after a crash on such filesystems.","solutions":["Stop or wait for the other Hugo process (usually `hugo server` or a running build), then retry.","Check the project directory is writable and delete a stale .hugo_build.lock if no Hugo process is running.","On filesystems with broken locking, set `noBuildLock: true` in config or pass `--noBuildLock` (accepting the concurrency risk).","Inspect the wrapped error text for the concrete OS-level cause (permissions, timeout)."],"exampleFix":"# before: `hugo new content posts/x.md` fails while `hugo server` is running a long build\n\n# after: stop the server, or if the lock is stale:\nrm .hugo_build.lock\nhugo new content posts/x.md","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"for i := 0; i < 3; i++ {\n    err = create.NewContent(h, kind, path, force)\n    if err == nil || !strings.Contains(err.Error(), \"build lock\") { break }\n    time.Sleep(time.Second << i)\n}","preventionTips":["Don't run hugo new while hugo server or another build holds the lock","Serialize CI jobs that write to the same site directory","Remove stale .hugo_build.lock only after confirming no hugo process is running"],"tags":["hugo","build-lock","concurrency","filesystem","cli"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}