{"id":"5082965b8fea5599","repo":"python-poetry/poetry","slug":"error-failed-to-clone-url-at-refspec-key-u","errorCode":null,"errorMessage":"<error>Failed to clone {url} at '{refspec.key}', unable to acquire file lock for {to_str(e.filename)}.</>","messagePattern":"<error>Failed to clone (.+?) at '(.+?)', unable to acquire file lock for (.+?)\\.</>","errorType":"exception","errorClass":"PoetryRuntimeError","httpStatus":null,"severity":"error","filePath":"src/poetry/vcs/git/backend.py","lineNumber":396,"sourceCode":"            try:\n                local.refs.import_refs(\n                    base=base,\n                    other={\n                        Ref(n[len(prefix) :]): v\n                        for (n, v) in remote_refs.refs.items()\n                        if n.startswith(prefix)\n                        and not n.endswith(PEELED_TAG_SUFFIX)\n                        and v is not None\n                    },\n                )\n            except FileLocked as e:\n\n                def to_str(path: bytes | str) -> str:\n                    if isinstance(path, bytes):\n                        path = path.decode()\n                    return path.replace(os.sep * 2, os.sep)\n\n                raise PoetryRuntimeError.create(\n                    # <https://github.com/jelmer/dulwich/pull/2045> should clean up the\n                    # ignore.\n                    reason=(\n                        f\"<error>Failed to clone {url} at '{refspec.key}',\"\n                        f\" unable to acquire file lock for {to_str(e.filename)}.</>\"\n                    ),\n                    info=[\n                        ERROR_MESSAGE_NOTE,\n                        ERROR_MESSAGE_PROBLEMS_SECTION_START,\n                        ERROR_MESSAGE_FILE_LOCK.format(\n                            lock_file=to_str(e.lockfilename)\n                        ),\n                    ],\n                )\n\n        try:\n            with local:\n                local.get_worktree().reset_index()","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/vcs/git/backend.py#L378-L414","documentation":"During dulwich _clone, when importing refs (refs/remotes/origin and refs/tags), a dulwich FileLocked exception means another process is holding (or left) a lock file inside the local clone/cache directory. PoetryRuntimeError reports the locked path and lock filename. This is a concurrency/stale-lock condition, not a bad ref.","triggerScenarios":"Two Poetry processes (e.g. parallel CI matrix jobs, an IDE plus a CLI) cloning the same repository into the same cached checkout simultaneously, or a previous clone that crashed and left a .lock file behind.","commonSituations":"Parallel builds sharing a Poetry/git cache directory; an interrupted `poetry install` leaving a stale dulwich lock; filesystem that doesn't reap locks cleanly.","solutions":["Remove the stale lock file(s) named in the exception (e.filename / lockfilename) under the clone/cache directory.","Avoid running concurrent Poetry operations against the same cache; give each job an isolated cache/venv.","Clear Poetry's git/VCS cache to force a clean re-clone.","Retry after ensuring no other process holds the lock."],"exampleFix":"# before - parallel jobs share $POETRY_CACHE_DIR -> FileLocked\n# after - give each job its own cache\nexport POETRY_CACHE_DIR=/tmp/poetry-cache-$CI_CONCURRENT_ID\npoetry install","handlingStrategy":"fallback","validationCode":"from pathlib import Path\n\ndef no_stale_locks(clone_dir: Path) -> bool:\n    return not any(clone_dir.rglob('*.lock'))","typeGuard":null,"tryCatchPattern":"from poetry.exceptions import PoetryRuntimeError\nfrom pathlib import Path\nimport shutil\n\ntry:\n    ...  # clone\nexcept PoetryRuntimeError as e:\n    if 'unable to acquire file lock' in str(e):\n        cache = Path.home() / '.cache' / 'pypoetry' / 'vcs'\n        shutil.rmtree(cache, ignore_errors=True)  # clear stale locks\n        raise","preventionTips":["Give each concurrent job its own POETRY_CACHE_DIR.","Remove stale dulwich .lock files after crashed runs.","Avoid running multiple Poetry processes against one cache directory."],"tags":["git","vcs","file-lock","concurrency","dulwich"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}