{"record":{"id":"0d22cd9d6917fdd8","repo":"coollabsio/coolify","slug":"failed-to-acquire-lock-for-ssh-key-keylocation","errorCode":null,"errorMessage":"Failed to acquire lock for SSH key: {$keyLocation}","messagePattern":"Failed to acquire lock for SSH key: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"app/Models/PrivateKey.php","lineNumber":222,"sourceCode":"    public function storeInFileSystem()\n    {\n        $filename = \"ssh_key@{$this->uuid}\";\n        $disk = Storage::disk('ssh-keys');\n        $keyLocation = $this->getKeyLocation();\n        $lockFile = $keyLocation.'.lock';\n\n        // Ensure the storage directory exists and is writable\n        $this->ensureStorageDirectoryExists();\n\n        // Use file locking to prevent concurrent writes from corrupting the key\n        $lockHandle = fopen($lockFile, 'c');\n        if ($lockHandle === false) {\n            throw new \\Exception(\"Failed to open lock file for SSH key: {$lockFile}\");\n        }\n\n        try {\n            if (! flock($lockHandle, LOCK_EX)) {\n                throw new \\Exception(\"Failed to acquire lock for SSH key: {$keyLocation}\");\n            }\n\n            // Attempt to store the private key\n            $success = $disk->put($filename, $this->private_key);\n\n            if (! $success) {\n                throw new \\Exception(\"Failed to write SSH key to filesystem. Check disk space and permissions for: {$keyLocation}\");\n            }\n\n            // Verify the file was actually created and has content\n            if (! $disk->exists($filename)) {\n                throw new \\Exception(\"SSH key file was not created: {$keyLocation}\");\n            }\n\n            $storedContent = $disk->get($filename);\n            if (empty($storedContent) || $storedContent !== $this->private_key) {\n                $disk->delete($filename); // Clean up the bad file\n                throw new \\Exception(\"SSH key file content verification failed: {$keyLocation}\");","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/coollabsio/coolify/blob/70b9acc42467278373e00de77abb40684e25b395/app/Models/PrivateKey.php#L204-L240","documentation":"Thrown by PrivateKey::storeInFileSystem() (app/Models/PrivateKey.php:222). After successfully fopen()ing the lock file, the code takes an exclusive flock(LOCK_EX) to prevent two workers from interleaving writes to the same key file. flock() returning false is rare on local filesystems and typically indicates the file lives on a filesystem that does not support advisory locks — most commonly NFS (especially NFSv4 without local locking), some FUSE mounts, or a Windows/SMB share.","triggerScenarios":"Storing/updating a PrivateKey when the 'ssh-keys' disk root is backed by NFS/FUSE/SMB where flock(LOCK_EX) fails; the lock file opened fine but advisory locking is unsupported.","commonSituations":"Self-hosted Coolify with /data/coolify on an NFS export 'for convenience'; NAS-backed bind mounts; container filesystems backed by unusual storage drivers.","solutions":["Move the ssh-keys storage off the network filesystem onto the container's local volume (local persistent dir for /data/coolify/ssh).","If NFS must be used, mount it with locking enabled (nolock removed; vers=4 with a running lock manager).","Retry the key save after remounting; the routine cleans up the lock handle in its finally block."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Detect lock-incapable storage before relying on flock\n$lockTest = $privateKey->getKeyLocation().'.probe.lock';\n$h = @fopen($lockTest, 'c');\nif ($h === false || ! @flock($h, LOCK_EX)) {\n    // advisory locks unsupported — move ssh-keys storage to a local filesystem\n}@fclose($h); @unlink($lockTest);","typeGuard":null,"tryCatchPattern":"try {\n    $privateKey->storeInFileSystem();\n} catch (\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Failed to acquire lock')) {\n        // NFS/FUSE storage: remount with locking or relocate the ssh-keys disk, then retry\n    }\n    throw $e;\n}","preventionTips":["Do not place /data/coolify on NFS/SMB/FUSE mounts; SSH key storage assumes local advisory locking.","If network storage is mandatory, mount NFS v4 with a working lock manager and verify with a flock probe."],"tags":["coolify","ssh-key","file-locking","nfs","file-storage"],"backgroundTag":"file-lock-acquisition-failed","analyzedSha":"70b9acc42467278373e00de77abb40684e25b395","analyzedAt":"2026-08-17T01:41:01.313Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}