{"record":{"id":"b9241d2f8327ae2a","repo":"phacility/phabricator","slug":"unable-to-lock-repository-s-only-clustered-rep","errorCode":null,"errorMessage":"Unable to lock repository \"%s\": only clustered repositories may be locked.","messagePattern":"Unable to lock repository \"(.+?)\": only clustered repositories may be locked\\.","errorType":"exception","errorClass":"PhutilArgumentUsageException","httpStatus":null,"severity":"error","filePath":"src/applications/repository/management/PhabricatorRepositoryManagementLockWorkflow.php","lineNumber":51,"sourceCode":"\n      if (!$repository->isHosted()) {\n        throw new PhutilArgumentUsageException(\n          pht(\n            'Unable to lock repository \"%s\": only hosted repositories may be '.\n            'locked.',\n            $display_name));\n      }\n\n      if (!$repository->supportsSynchronization()) {\n        throw new PhutilArgumentUsageException(\n          pht(\n            'Unable to lock repository \"%s\": only repositories that support '.\n            'clustering may be locked.',\n            $display_name));\n      }\n\n      if (!$repository->getAlmanacServicePHID()) {\n        throw new PhutilArgumentUsageException(\n          pht(\n            'Unable to lock repository \"%s\": only clustered repositories '.\n            'may be locked.',\n            $display_name));\n      }\n    }\n\n    $diffusion_phid = id(new PhabricatorDiffusionApplication())\n      ->getPHID();\n\n    $locks = array();\n    foreach ($repositories as $repository) {\n      $engine = id(new DiffusionRepositoryClusterEngine())\n        ->setViewer($viewer)\n        ->setActingAsPHID($diffusion_phid)\n        ->setRepository($repository);\n\n      $event = $engine->newMaintenanceEvent();","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/phacility/phabricator/blob/5720a38cfe95b00ca4be5016dd0d2f3195f4fa04/src/applications/repository/management/PhabricatorRepositoryManagementLockWorkflow.php#L33-L69","documentation":"Third pre-flight guard in `bin/repository lock`: the repository passes the hosted and VCS-type checks but `getAlmanacServicePHID()` is null, meaning it is not bound to an Almanac \"cluster repository\" service. Locking exists to fence cluster replicas, so a repository living only on the local disk is rejected. All three checks run before any `PhabricatorGlobalLock` is acquired, so nothing is partially locked.","triggerScenarios":"Running `./bin/repository lock R1` on a single-server install where the repository has no Almanac service binding; a repo allocated to a device instead of a cluster repository service.","commonSituations":"Operators copy clustering runbook commands onto non-clustered installs; after removing a cluster binding the lock script still targets that repo.","solutions":["Only run lock against repositories allocated to an Almanac cluster repository service (check Repository → Edit Cluster → service binding).","If clustering is intended, create the Almanac service/bindings and allocate the repository to it, then retry.","On single-server installs, use `bin/repository maintenance` or stop daemons instead of cluster locking."],"exampleFix":"// before\n$ ./bin/repository lock R1   # R1 not bound to an Almanac service\n[1169] Unable to lock repository \"rR1\": only clustered repositories may be locked.\n\n// after\n$ ./bin/repository maintenance R1 --start \"maintenance window\"   # non-cluster alternative","handlingStrategy":"validation","validationCode":"# Only attempt locking on installs with a cluster repository service;\n# verify a repo shows an Almanac service binding (Repository -> Edit Cluster) before locking it.","typeGuard":"function is_clustered(PhabricatorRepository $repository): bool {\n  return $repository->getAlmanacServicePHID() !== null;\n}","tryCatchPattern":null,"preventionTips":["Reserve `bin/repository lock` for clustered installs; use maintenance mode elsewhere.","After changing Almanac bindings, re-check that target repos are still allocated to a cluster service."],"tags":["phabricator","phorge","cli","locking","almanac","clustering","precondition"],"backgroundTag":"repository-not-clustered","analyzedSha":"5720a38cfe95b00ca4be5016dd0d2f3195f4fa04","analyzedAt":"2026-08-21T05:07:25.672Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}