{"id":"614f539a7c6bac3d","repo":"python-poetry/poetry","slug":"error-failed-to-checkout-url-at-revision","errorCode":null,"errorMessage":"<error>Failed to checkout {url} at '{revision}'.</>","messagePattern":"<error>Failed to checkout (.+?) at '(.+?)'\\.</>","errorType":"exception","errorClass":"PoetryRuntimeError","httpStatus":null,"severity":"error","filePath":"src/poetry/vcs/git/backend.py","lineNumber":310,"sourceCode":"        except CalledProcessError as e:\n            raise PoetryRuntimeError.create(\n                reason=f\"<error>Failed to clone <info>{url}</>, check your git configuration and permissions for this repository.</>\",\n                exception=e,\n                info=[\n                    ERROR_MESSAGE_NOTE,\n                    ERROR_MESSAGE_PROBLEMS_SECTION_START_NETWORK_ISSUES,\n                    ERROR_MESSAGE_BAD_REMOTE.format(remote=url),\n                ],\n            )\n\n        if revision:\n            revision = revision.removeprefix(\"refs/heads/\")\n            revision = revision.removeprefix(\"refs/tags/\")\n\n        try:\n            SystemGit.checkout(revision, target)\n        except CalledProcessError as e:\n            raise PoetryRuntimeError.create(\n                reason=f\"<error>Failed to checkout {url} at '{revision}'.</>\",\n                exception=e,\n                info=[\n                    ERROR_MESSAGE_NOTE,\n                    ERROR_MESSAGE_PROBLEMS_SECTION_START_NETWORK_ISSUES,\n                    ERROR_MESSAGE_BAD_REVISION.format(revision=revision),\n                ],\n            )\n\n        repo = Repo(str(target))\n        return repo\n\n    @classmethod\n    def _clone(cls, url: str, refspec: GitRefSpec, target: Path) -> Repo:\n        \"\"\"\n        Helper method to clone a remove repository at the given `url` at the specified\n        ref spec.\n        \"\"\"","sourceCodeStart":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/vcs/git/backend.py#L292-L328","documentation":"In _clone_legacy, after a successful system-git clone, SystemGit.checkout(revision) is run; a CalledProcessError there raises PoetryRuntimeError. The revision (resolved from refspec.tag/branch/revision, stripped of refs/heads/ and refs/tags/ prefixes) could not be checked out.","triggerScenarios":"A git dependency declares a rev/branch/tag that does not exist in the freshly cloned repository, or the working tree is in a state preventing checkout.","commonSituations":"Typo in a branch/tag name; the ref was deleted/renamed on the remote after pyproject was written; rev points to a commit not present in a shallow clone; force-pushed history.","solutions":["Confirm the revision exists with `git ls-remote <url>` or by cloning manually and checking out.","Correct the rev/branch/tag value in pyproject.toml's git dependency.","If the ref was removed upstream, update to an existing ref.","Clear Poetry's git cache so a fresh clone is performed."],"exampleFix":"# before\n[tool.poetry.dependencies]\nlib = { git = \"https://github.com/acme/lib.git\", branch = \"devel\" }  # branch deleted\n# after\nlib = { git = \"https://github.com/acme/lib.git\", rev = \"abcdef0\" }","handlingStrategy":"validation","validationCode":"import subprocess\n\ndef ref_exists(url: str, revision: str) -> bool:\n    out = subprocess.run(\n        ['git', 'ls-remote', url], capture_output=True, text=True,\n    ).stdout\n    return any(revision in line for line in out.splitlines())","typeGuard":null,"tryCatchPattern":"from poetry.exceptions import PoetryRuntimeError\ntry:\n    ...\nexcept PoetryRuntimeError as e:\n    if \"Failed to checkout\" in str(e):\n        # verify/fix the revision\n        raise","preventionTips":["Confirm revisions with `git ls-remote` before pinning them.","Prefer full commit shas over symbolic branch/tag names for reproducibility.","Update pyproject when upstream renames/deletes refs."],"tags":["git","vcs","checkout","revision"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}