{"id":"fa8a0ab03ce436a3","repo":"python-poetry/poetry","slug":"error-failed-to-clone-url-at-refspec-key-v","errorCode":null,"errorMessage":"<error>Failed to clone {url} at '{refspec.key}', verify ref exists on remote.</>","messagePattern":"<error>Failed to clone (.+?) at '(.+?)', verify ref exists on remote\\.</>","errorType":"exception","errorClass":"PoetryRuntimeError","httpStatus":null,"severity":"error","filePath":"src/poetry/vcs/git/backend.py","lineNumber":345,"sourceCode":"        ref spec.\n        \"\"\"\n        local: Repo\n        if not target.exists():\n            local = Repo.init(str(target), mkdir=True)\n            porcelain.remote_add(local, \"origin\", url)\n        else:\n            local = Repo(str(target))\n\n        remote_refs = cls._fetch_remote_refs(url=url, local=local)\n\n        logger.debug(\n            \"Cloning <c2>%s</> at '<c2>%s</>' to <c1>%s</>\", url, refspec.key, target\n        )\n\n        try:\n            refspec.resolve(remote_refs=remote_refs, repo=local)\n        except KeyError:  # branch / ref does not exist\n            raise PoetryRuntimeError.create(\n                reason=f\"<error>Failed to clone {url} at '{refspec.key}', verify ref exists on remote.</>\",\n                info=[\n                    ERROR_MESSAGE_NOTE,\n                    ERROR_MESSAGE_PROBLEMS_SECTION_START_NETWORK_ISSUES,\n                    ERROR_MESSAGE_BAD_REVISION.format(revision=refspec.key),\n                ],\n            )\n\n        try:\n            # ensure local HEAD matches remote\n            ref = remote_refs.refs[Ref(b\"HEAD\")]\n            if ref is not None:\n                local.refs[Ref(b\"HEAD\")] = ref\n        except ValueError:\n            raise PoetryRuntimeError.create(\n                reason=f\"<error>Failed to clone {url} at '{refspec.key}', verify ref exists on remote.</>\",\n                info=[\n                    ERROR_MESSAGE_NOTE,","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/vcs/git/backend.py#L327-L363","documentation":"In the dulwich-based _clone, after fetching remote refs, refspec.resolve(remote_refs, repo=local) is called. A KeyError from resolve means the requested branch/tag/revision is not present among the advertised remote refs, so PoetryRuntimeError is raised telling you to verify the ref exists on the remote.","triggerScenarios":"A git dependency whose rev/branch/tag is not advertised by the remote (typo, deleted ref, ref only in a fork), cloned via dulwich.","commonSituations":"Branch renamed or deleted upstream; rev is a short sha ambiguous or absent; pointing at a tag that doesn't exist; ref lives only on a different remote/fork.","solutions":["Run `git ls-remote <url>` to confirm the ref is actually advertised.","Fix the rev/branch/tag in pyproject.toml to an existing remote ref.","Push the missing ref to the remote if it should be there.","Use an explicit full commit sha to avoid ambiguity."],"exampleFix":"# before\nlib = { git = \"https://github.com/acme/lib.git\", tag = \"v1.2\" }  # tag does not exist\n# after - verify with: git ls-remote --tags https://github.com/acme/lib.git\nlib = { git = \"https://github.com/acme/lib.git\", tag = \"v1.2.3\" }","handlingStrategy":"validation","validationCode":"import subprocess\n\ndef remote_has_ref(url: str, ref: str) -> bool:\n    out = subprocess.run(\n        ['git', 'ls-remote', url], capture_output=True, text=True,\n    ).stdout\n    return any(ref in line for line in out.splitlines())","typeGuard":null,"tryCatchPattern":"from poetry.exceptions import PoetryRuntimeError\ntry:\n    ...  # operation triggering a dulwich clone\nexcept PoetryRuntimeError as e:\n    if 'verify ref exists on remote' in str(e):\n        raise","preventionTips":["Use `git ls-remote <url>` to confirm the ref is advertised.","Pin to concrete commit shas to avoid ref resolution failures.","Update pyproject when upstream refs are renamed or deleted."],"tags":["git","vcs","dulwich","revision","clone"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}