python-poetry/poetry · error · PoetryRuntimeError

Failed to clone </>, check your git configuration and…

Error message

<error>Failed to clone <info>{url}</>, check your git configuration and permissions for this repository.</>

What it means

In the legacy clone path (_clone_legacy), Poetry falls back to the system `git` binary via SystemGit.clone. If that subprocess returns non-zero (CalledProcessError), it raises PoetryRuntimeError with hints to check git config and permissions. This is the 'system git clone failed' error, used when dulwich is not used for cloning.

Solutions

1. Manually run `git clone <url>` in a shell to reproduce and read git's own error.
2. Configure credentials: HTTPS via `poetry config http-basic.<repo>` or a token, SSH via a usable key + known_hosts.
3. Check network/proxy reachability and that git is installed and on PATH.
4. Correct the repository URL in pyproject.toml / source config.

Example fix

# before - private https repo, no credentials
git = 'git+https://gitlab.internal/acme/lib.git'
# after - configure auth and use a reachable url
poetry config http-basic.gitlab '$USER' '$TOKEN'
git = 'git+https://gitlab.internal/acme/lib.git'

import subprocess

def git_clone_ok(url: str) -> bool:
    return subprocess.run(
        ['git', 'ls-remote', '--exit-code', url],
        capture_output=True,
    ).returncode == 0

from poetry.exceptions import PoetryRuntimeError
try:
    # operation that triggers a clone
    ...
except PoetryRuntimeError as e:
    if 'Failed to clone' in str(e):
        # check creds, network, url
        raise

When it happens

Trigger: Cloning a git dependency via the system-git fallback when `git clone <url>` fails: wrong/unreachable URL, private repo without credentials, no network, proxy block, or git not installed.

Common situations: HTTPS private repo with no token configured; SSH repo without a deployed key; corporate proxy/firewall blocking the host; misspelled git URL; git missing on PATH.

Related errors

• Failed to clone at ' ', verify ref exists on remote.</>
• Failed to checkout at ' '.</>
• Failed to clone at ' ', unable to acquire file lock for .</>
• HTTP Error : |
• Invalid Git parameter

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

Appendix: source

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

    @staticmethod
    def _clone_legacy(url: str, refspec: GitRefSpec, target: Path) -> Repo:
        """
        Helper method to facilitate fallback to using system provided git client via
        subprocess calls.
        """
        from poetry.vcs.git.system import SystemGit

        logger.debug("Cloning '%s' using system git client", url)

        if target.exists():
            remove_directory(path=target, force=True)

        revision = refspec.tag or refspec.branch or refspec.revision or "HEAD"

        try:
            SystemGit.clone(url, target)
        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}'.</>",

View on GitHub (pinned to 92b74dcfe3)