composer/composer · error · RuntimeException

fossil was not found, check that it is installed and in…

Error message

fossil was not found, check that it is installed and in your PATH env.

${errorOutput}

What it means

Thrown by FossilDriver::checkFossil() when `fossil version` exits non-zero. The fossil binary is not found or not executable from the current environment. The process error output is appended to guide diagnosis.

Solutions

Install fossil (e.g. apt-get install fossil, or download the single static binary from fossil-scm.org).
Ensure the fossil binary is on PATH for the process running Composer.
In Docker/CI, add an install step to the image.

Defensive patterns

Strategy: validation

Validate before calling

$proc = new \Composer\Util\ProcessExecutor();
if ($proc->execute(['fossil', 'version'], $out) !== 0) {
    throw new \RuntimeException('fossil binary not available; install it and add to PATH.');
}

Prevention

Ensure fossil is installed and on PATH before using FossilDriver.
Add a fossil install step to CI/container images.
Guard against this by probing `fossil version` at startup in environments you don't control.

When it happens

Trigger: Any FossilDriver operation (initialize()) on a host where the fossil SCM binary is not installed or not on PATH.

Common situations: Minimal containers/CI images without fossil installed; PATH not inherited by the process; permissions preventing execution.

Related errors

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

Appendix: source

Thrown at src/Composer/Repository/Vcs/FossilDriver.php:76

            $localName = Preg::replace('{[^a-z0-9]}i', '-', $this->url);
            $this->repoFile = $this->config->get('cache-repo-dir') . '/' . $localName . '.fossil';
            $this->checkoutDir = $this->config->get('cache-vcs-dir') . '/' . $localName . '/';

            $this->updateLocalRepo();
        }

        $this->getTags();
        $this->getBranches();
    }

    /**
     * Check that fossil can be invoked via command line.
     */
    protected function checkFossil(): void
    {
        if (0 !== $this->process->execute(['fossil', 'version'], $ignoredOutput)) {
            throw new \RuntimeException("fossil was not found, check that it is installed and in your PATH env.\n\n" . $this->process->getErrorOutput());
        }
    }

    /**
     * Clone or update existing local fossil repository.
     */
    protected function updateLocalRepo(): void
    {
        assert($this->repoFile !== null);

        $fs = new Filesystem();
        $fs->ensureDirectoryExists($this->checkoutDir);

        if (!is_writable(dirname($this->checkoutDir))) {
            throw new \RuntimeException('Can not clone '.Url::sanitize($this->url).' to access package information. The "'.$this->checkoutDir.'" directory is not writable by the current user.');
        }

        // update the repo if it is a valid fossil repository

View on GitHub (pinned to c435d285c9)