{"record":{"id":"6a44914a9dae8189","repo":"docker/compose","slug":"cannot-take-exclusive-lock-for-project-q-w","errorCode":null,"errorMessage":"cannot take exclusive lock for project %q: %w","messagePattern":"cannot take exclusive lock for project %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/compose/watch.go","lineNumber":99,"sourceCode":"\t// so env_file declared by unrelated services doesn't need to exist\n\tproject, err = project.WithServicesEnvironmentResolved(true)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif err := applyPlatforms(project, true); err != nil {\n\t\treturn err\n\t}\n\n\tbuild, err := buildOpts.toAPIBuildOptions(nil)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// validation done -- ensure we have the lockfile for this project before doing work\n\tl, err := locker.NewPidfile(project.Name)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot take exclusive lock for project %q: %w\", project.Name, err)\n\t}\n\tif err := l.Lock(); err != nil {\n\t\treturn fmt.Errorf(\"cannot take exclusive lock for project %q: %w\", project.Name, err)\n\t}\n\n\tif !watchOpts.noUp {\n\t\tfor index, service := range project.Services {\n\t\t\tif service.Build != nil && service.Develop != nil {\n\t\t\t\tservice.PullPolicy = types.PullPolicyBuild\n\t\t\t}\n\t\t\tproject.Services[index] = service\n\t\t}\n\t\tupOpts := api.UpOptions{\n\t\t\tCreate: api.CreateOptions{\n\t\t\t\tBuild:                &build,\n\t\t\t\tServices:             services,\n\t\t\t\tRemoveOrphans:        false,\n\t\t\t\tRecreate:             api.RecreateDiverged,","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/cmd/compose/watch.go#L81-L117","documentation":"Returned by `docker compose watch` when locker.NewPidfile(project.Name) fails while creating the project lockfile (typically under ~/.docker/compose/ or the configured lock dir). NewPidfile errors when the pidfile path cannot be created or written (permissions, invalid project name characters, read-only home). The lock enforces a single active watch/up session per project, so creation failure aborts before any watch work.","triggerScenarios":"Unwritable lock directory (permissions changed, read-only filesystem, sandboxed container with read-only HOME); a project name that sanitizes to a path with invalid characters; disk-full or SELinux denial on the lockdir; running watch as a different user than the one owning existing lock files.","commonSituations":"Running `docker compose watch` inside a dev container or CI where HOME is read-only; root vs non-root ownership conflicts on the lock directory; systems with restrictive umask/ACLs on ~/.docker.","solutions":["Inspect the wrapped error's cause — it names the underlying file operation that failed.","Fix permissions on the lock directory (commonly ~/.docker/compose or $XDG-style lockdir): `chmod`/`chown` it to the running user.","If HOME is read-only (containers/CI), mount or point the lock location at a writable path, or run as a user with a writable home.","As a last resort remove a stale/corrupt pidfile for the project after verifying no watch process is running."],"exampleFix":"# before (lockdir not writable by current user)\ndocker compose watch\n\n# after\nchmod -R u+w ~/.docker/compose   # or run as the owning user\ndocker compose watch","handlingStrategy":"try-catch","validationCode":"# ensure the lock dir is writable before watch\nLOCKDIR=\"$HOME/.docker/compose\"\n[ -w \"$LOCKDIR\" ] || { echo \"lock dir not writable: $LOCKDIR\" >&2; exit 2; }","typeGuard":null,"tryCatchPattern":"err := runWatch(...); if err != nil && strings.Contains(err.Error(), \"cannot take exclusive lock\") { /* inspect wrapped cause: perms/path; fix lockdir ownership or redirect to writable HOME; do NOT blindly retry */ }","preventionTips":["Run watch as the user owning ~/.docker.","In containers/CI, ensure HOME is writable or mount the lock dir.","Read the wrapped error — creation failure vs lock contention have different fixes."],"tags":["cli","watch","locking","filesystem","permissions","compose"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}