{"record":{"id":"1b5fb90de4cb4c43","repo":"pkgxdev/pkgx","slug":"unexpected-error-install-locking-failed","errorCode":null,"errorMessage":"unexpected error: install locking failed","messagePattern":"unexpected error: install locking failed","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/lib/src/install.rs","lineNumber":62,"sourceCode":"\n    #[cfg(windows)]\n    let lockfile = OpenOptions::new()\n        .read(true)\n        .write(true)\n        .create(true)\n        .truncate(true)\n        .open(shelf.join(\"lockfile\"))?;\n    #[cfg(not(windows))]\n    let lockfile = OpenOptions::new()\n        .read(true) // Open the directory in read-only mode\n        .open(shelf.clone())?;\n\n    task::spawn_blocking({\n        let lockfile = lockfile.try_clone()?;\n        move || {\n            lockfile\n                .lock_exclusive()\n                .expect(\"unexpected error: install locking failed\");\n        }\n    })\n    .await?;\n\n    let dst_path = cellar::dst(pkg, config);\n\n    // did another instance of pkgx install us while we waited for the lock?\n    // if so, we’re good: eject\n    if dst_path.is_dir() {\n        FileExt::unlock(&lockfile)?;\n        return Ok(Installation {\n            path: dst_path,\n            pkg: pkg.clone(),\n        });\n    }\n\n    let url = inventory::get_url(pkg, config);\n    let client = build_client()?;","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/pkgxdev/pkgx/blob/6de1d7e953b98061f69db95d4bd45a2a6ee5d7da/crates/lib/src/install.rs#L44-L80","documentation":"During `install`, an exclusive advisory lock (`lock_exclusive`) is taken on a lockfile in a blocking task. The code treats lock failure as unrecoverable and calls `.expect(\"unexpected error: install locking failed\")`, i.e. it panics rather than returning an error. This indicates the OS refused the flock on the install lockfile — not a concurrency wait, but an actual failure to acquire the lock.","triggerScenarios":"Calling `install()` when the lockfile descriptor cannot be flocked — typically a filesystem that doesn't support advisory locks (some network mounts, certain overlay/tmpfs setups, Windows FAT), or an fd that was already closed/invalid because try_clone or the underlying file failed.","commonSituations":"Installing into a cellar on NFS/CIFS/SMB shares that don't support flock, running in containers with exotic mount options, or low-level fd exhaustion causing lock_exclusive to fail unexpectedly.","solutions":["Move the cellar (PKGX_DIR) onto a local filesystem that supports flock (ext4, apfs, ntfs)","Retry the install — transient fd/EPERM conditions usually disappear on a rerun","Check mount options of the cellar filesystem (`mount | grep <cellar>`) and remount without NFS if flock is unsupported","Report a panic: this expect should ideally be a returned error rather than an abort"],"exampleFix":"// before\nlockfile\n    .lock_exclusive()\n    .expect(\"unexpected error: install locking failed\");\n// after\nlockfile\n    .lock_exclusive()\n    .context(\"install locking failed\")?;","handlingStrategy":"retry","validationCode":"fn cellar_supports_flock(cellar: &std::path::Path) -> bool {\n    // probe: create a temp file and try an exclusive flock\n    std::fs::OpenOptions::new().create(true).write(true)\n        .open(cellar.join(\".pkgx-flock-probe\"))\n        .ok()\n        .and_then(|f| fs2::FileExt::try_lock_exclusive(&f).ok())\n        .is_some()\n}","typeGuard":null,"tryCatchPattern":"// the lib panics here, so guard the process, not the error\n// run installs in a wrapper that detects this panic and retries on local FS:\nlet status = cmd.status()?;\nif !status.success() && output_contains(\"install locking failed\") {\n    eprintln!(\"cellar FS may not support flock; retrying on local disk\");\n    // switch PKGX_DIR to a local path and retry\n}","preventionTips":["Keep the cellar on a local filesystem that supports advisory locks","Avoid NFS/CIFS/SMB cellars, especially in containers","Monitor for the panic string in wrapper scripts and fall back to a local PKGX_DIR","Prefer running installs as a normal user with a valid local ~/.pkgx"],"tags":["locking","filesystem","concurrency","panic"],"backgroundTag":"file-open-failed","analyzedSha":"6de1d7e953b98061f69db95d4bd45a2a6ee5d7da","analyzedAt":"2026-09-10T09:59:03.886Z","contentChangedAt":"2026-09-10T09:59:03.886Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}