passbolt/passbolt_api · error · CakeException

$healthcheckService->getFailureMessage()

Error message

$healthcheckService->getFailureMessage()

What it means

During 'bin/cake passbolt install', every registered healthcheck service is run; if any healthcheck->check() fails (isPassed() false), InstallCommand aborts by throwing a CakeException whose message comes from the failing healthcheck's getFailureMessage(). It is a generic gate: the actual cause is whatever subsystem failed (GPG, SSL, database, config, etc.).

Solutions

1. Run 'bin/cake passbolt healthcheck' as the message suggests — it names the exact failing check and remediation.
2. Fix the specific failing check (e.g. generate server key, fix config/keys/ssl) before re-running install.
3. Ensure the command runs as the web server user (e.g. su -s /bin/bash -c 'bin/cake passbolt install' www-data) since some checks are user/permission-sensitive.
4. Verify env variables and passbolt.php values with 'bin/cake passbolt verify' or a config review.

Example fix

// before: install aborts
$ bin/cake passbolt install
Error: The server key does not exist...
// after: fix the check then retry
$ sudo su -s /bin/bash -c './bin/cake passbolt create_gpg_server_key' www-data
$ bin/cake passbolt install

$healthcheck = new FooHealthcheck();
$healthcheck->check();
if (!$healthcheck->isPassed()) {
    fwrite(STDERR, 'Install would fail: ' . $healthcheck->getFailureMessage() . PHP_EOL);
    exit(1);
}

try {
    (new InstallCommand())->execute($args, $io);
} catch (CakeException $e) {
    // run 'bin/cake passbolt healthcheck' and fix the named check
    $this->error($e->getMessage());
}

When it happens

Trigger: Running the install command in an environment where any healthcheck fails: missing server GPG key, unparseable SSL certificate, invalid passbolt.php config, unreachable database, bad folder permissions, etc.

Common situations: Fresh installs with incomplete passbolt.php; server key not generated (bin/cake passbolt create_gpg_server_key); self-signed or expired SSL certs; wrong database credentials; running install twice after partial failure.

Related errors

• [FAIL] </error>
• [WARN] </warning>
• The file does not exist
• The ldap integration is not configured or it is disabled
• group(s) returned by your directory are invalid and will be…

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/beadd52f346d1825. Report an issue: GitHub.

Appendix: source

Thrown at src/Command/InstallCommand.php:419

     *
     * @param \Cake\Console\Arguments $args Arguments.
     * @param \Cake\Console\ConsoleIo $io Console IO.
     * @return bool status success
     */
    protected function healthchecks(Arguments $args, ConsoleIo $io): bool
    {
        $io->nl();
        $io->out(__('Running baseline checks, please wait...'));
        $healthcheckServices = $this->getInstallCheckHealthcheckServices();
        try {
            foreach ($healthcheckServices as $healthcheckService) {
                if ($healthcheckService instanceof HealthcheckWithOptionsInterface) {
                    $healthcheckService->setOptions($args->getOptions());
                }

                $healthcheckService->check();
                if (!$healthcheckService->isPassed()) {
                    throw new CakeException($healthcheckService->getFailureMessage());
                }
            }
        } catch (CakeException $e) {
            $this->error($e->getMessage(), $io);
            $this->error(__('Please run ./bin/cake passbolt healthcheck for more information and help.'), $io);

            return false;
        }

        // If force is false, and database is populated, warn
        if (!$args->getOption('force')) {
            /** @var \App\Service\Healthcheck\Database\TablesCountDatabaseHealthcheck $tableCountCheck */
            $tableCountCheck = $this->healthcheckServiceCollector
                ->getService(TablesCountDatabaseHealthcheck::class);
            $tableCountCheck->check();
            if ($tableCountCheck->isPassed()) {
                $msg = __('Some tables are already present in the database.') . ' ';
                $msg .= __('A new installation would override existing data.');

View on GitHub (pinned to 31c1bbc10f)