python-poetry/poetry · error · PoetryRuntimeError

<error>Failed to checkout {url} at '{revision}'.</>

Error message

<error>Failed to checkout {url} at '{revision}'.</>

What it means

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.

Source

Thrown at src/poetry/vcs/git/backend.py:310

        except CalledProcessError as e:
            raise PoetryRuntimeError.create(
                reason=f"<error>Failed to clone <info>{url}</>, check your git configuration and permissions for this repository.</>",
                exception=e,
                info=[
                    ERROR_MESSAGE_NOTE,
                    ERROR_MESSAGE_PROBLEMS_SECTION_START_NETWORK_ISSUES,
                    ERROR_MESSAGE_BAD_REMOTE.format(remote=url),
                ],
            )

        if revision:
            revision = revision.removeprefix("refs/heads/")
            revision = revision.removeprefix("refs/tags/")

        try:
            SystemGit.checkout(revision, target)
        except CalledProcessError as e:
            raise PoetryRuntimeError.create(
                reason=f"<error>Failed to checkout {url} at '{revision}'.</>",
                exception=e,
                info=[
                    ERROR_MESSAGE_NOTE,
                    ERROR_MESSAGE_PROBLEMS_SECTION_START_NETWORK_ISSUES,
                    ERROR_MESSAGE_BAD_REVISION.format(revision=revision),
                ],
            )

        repo = Repo(str(target))
        return repo

    @classmethod
    def _clone(cls, url: str, refspec: GitRefSpec, target: Path) -> Repo:
        """
        Helper method to clone a remove repository at the given `url` at the specified
        ref spec.
        """

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Confirm the revision exists with `git ls-remote <url>` or by cloning manually and checking out.
2. Correct the rev/branch/tag value in pyproject.toml's git dependency.
3. If the ref was removed upstream, update to an existing ref.
4. Clear Poetry's git cache so a fresh clone is performed.

Example fix

# before
[tool.poetry.dependencies]
lib = { git = "https://github.com/acme/lib.git", branch = "devel" }  # branch deleted
# after
lib = { git = "https://github.com/acme/lib.git", rev = "abcdef0" }

import subprocess

def ref_exists(url: str, revision: str) -> bool:
    out = subprocess.run(
        ['git', 'ls-remote', url], capture_output=True, text=True,
    ).stdout
    return any(revision in line for line in out.splitlines())

from poetry.exceptions import PoetryRuntimeError
try:
    ...
except PoetryRuntimeError as e:
    if "Failed to checkout" in str(e):
        # verify/fix the revision
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• <error>Failed to clone {url} at '{refspec.key}', verify ref
• Unsupported VCS dependency {vcs}
• <error>Failed to clone <info>{url}</>, check your git config
• <error>Failed to clone {url} at '{refspec.key}', unable to a
• Invalid Git parameter: {parameter}

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/614f539a7c6bac3d.json. Report an issue: GitHub.