composer/composer · error · RuntimeException

Failed to execute {command} {errorOutput}

Error message

Failed to execute {command}

{errorOutput}

What it means

Thrown by HgDownloader::doInstall() after a successful `hg clone` when `hg up -- <sourceReference>` exits non-zero. The clone worked but the checkout of the specific revision failed, typically because the reference does not exist in the cloned repository.

Source

Thrown at src/Composer/Downloader/HgDownloader.php:51

        return \React\Promise\resolve(null);
    }

    /**
     * @inheritDoc
     */
    protected function doInstall(PackageInterface $package, string $path, string $url): PromiseInterface
    {
        $hgUtils = new HgUtils($this->io, $this->config, $this->process);

        $cloneCommand = static function (string $url) use ($path): array {
            return ['hg', 'clone', '--', $url, $path];
        };

        $hgUtils->runCommand($cloneCommand, $url, $path);

        $command = ['hg', 'up', '--', (string) $package->getSourceReference()];
        if (0 !== $this->process->execute($command, $ignoredOutput, realpath($path))) {
            throw new \RuntimeException('Failed to execute ' . implode(' ', $command) . "\n\n" . $this->process->getErrorOutput());
        }

        return \React\Promise\resolve(null);
    }

    /**
     * @inheritDoc
     */
    protected function doUpdate(PackageInterface $initial, PackageInterface $target, string $path, string $url): PromiseInterface
    {
        $hgUtils = new HgUtils($this->io, $this->config, $this->process);

        $ref = $target->getSourceReference();
        $this->io->writeError(" Updating to ".$target->getSourceReference());

        if (!$this->hasMetadataRepository($path)) {
            throw new \RuntimeException('The .hg directory is missing from '.$path.', see https://getcomposer.org/commit-deps for more information');
        }

View on GitHub (pinned to 6ffc117740)

Solutions

1. Run `composer update <pkg>` to resolve a fresh, valid source reference.
2. Manually clone the repo and run `hg up -- <ref>` to confirm the reference is missing, then report to the maintainer.
3. Clear the cache and re-install to rule out a stale clone.
4. Switch to --prefer-dist if the provider publishes archives.

Example fix

# before: locked hg revision no longer exists
composer install --prefer-source

# after
composer update pkg-name
# verify manually:
hg clone <url> /tmp/pkg && hg -R /tmp/pkg up -- <ref>

// Verify the hg revision exists in the repo before checkout
exec(sprintf('hg identify -r %s %s 2>&1', escapeshellarg($ref), escapeshellarg($url)), $out, $code);
if ($code !== 0) {
    // ref invalid — update package lock before attempting install
    throw new \RuntimeException("hg ref $ref not found at $url");
}

try {
    $downloader->install($package, $path, $url);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'Failed to execute hg up')) {
        // refresh lock to a valid revision and retry
        // composer update <pkg> then re-install
    }
    throw $e;
}

When it happens

Trigger: Installing an hg-sourced package with --prefer-source; the clone succeeds but the source reference in composer.lock is not present (history rewritten, revision stripped, or wrong ref).

Common situations: An upstream hg repo that had revisions stripped or a branch closed; composer.lock points to a revision that no longer exists; a mismatched source URL.

Related errors

• Failed to execute {command} {errorOutput}{exceptionExtra}
• hg was not found in your PATH, skipping source download
• The .hg directory is missing from {path}, see https://getcom
• Failed to clone ${url}, hg was not found, check that it is i
• Valid composer.json and composer.lock files are required to

AI-assisted analysis of composer/composer@6ffc117740 (2026-08-07). Data as JSON: /api/errors/ffe83eec3b112060. Report an issue: GitHub.