# ERROR: Command errored out with exit status 255: hg clone 'https://hg.example.com/package' /tmp/pip-req-build-xxxxx

- **ID:** `pip/mercurial-clone-fail`
- **Domain:** pip
- **Category:** install_error
- **Error Code:** `ERROR`
- **Verification:** ai_generated
- **Fix Rate:** 88%

## Root Cause

pip fails to clone a Mercurial (hg) repository because the build dependency is specified as a VCS URL with hg+ scheme but the Mercurial client is not installed or the repository URL is incorrect.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| pip 23.2 | active | — | — |
| pip 24.0 | active | — | — |
| pip 24.1 | active | — | — |
| Mercurial 6.5 | active | — | — |
| Mercurial 6.6 | active | — | — |

## Workarounds

1. **Install Mercurial client via system package manager: sudo apt-get install mercurial (Debian/Ubuntu) or brew install mercurial (macOS). Then retry pip install.** (95% success)
   ```
   Install Mercurial client via system package manager: sudo apt-get install mercurial (Debian/Ubuntu) or brew install mercurial (macOS). Then retry pip install.
   ```
2. **Use a published wheel or tarball instead of the VCS URL: pip install package --no-index --find-links https://pypi.org/simple/** (80% success)
   ```
   Use a published wheel or tarball instead of the VCS URL: pip install package --no-index --find-links https://pypi.org/simple/
   ```
3. **Switch to a Git mirror if available: pip install git+https://github.com/user/package.git** (85% success)
   ```
   Switch to a Git mirror if available: pip install git+https://github.com/user/package.git
   ```

## Dead Ends

- **** — Running pip install with --no-clean does not fix the missing hg client; it only preserves the partial clone directory for debugging. (95% fail)
- **** — Using pip install --force-reinstall does not install the Mercurial client; it only re-downloads packages without addressing the missing VCS tool. (98% fail)
- **** — Setting PIP_REQUIRE_VIRTUALENV=true does not bypass the hg clone issue; virtual environment activation is unrelated. (90% fail)