What causes "The database cannot be installed" in passbolt/passbolt_api?

Re-check the database form values (host, port, database, user, password) and that the user has full privileges on the schema.

passbolt/passbolt_api · critical · Exception

The database cannot be installed

Error message

The database cannot be installed

What it means

WebInstaller::installDatabase() runs the CakePHP migrations via the Migrations (phinx) wrapper and throws when migrate() reports that nothing was migrated. It signals the web installer could not create or update the passbolt database schema.

Solutions

Re-check the database form values (host, port, database, user, password) and that the user has full privileges on the schema.
Run the migration from CLI to see the underlying phinx error: bin/cake passbolt migrate; fix the reported SQL or connection error.
Confirm the database server version is supported (MySQL 5.7/8, MariaDB >= 10.4, Postgres > 14).
Check for a leftover migration lock or failed migration state, resolve it, then retry the install step.

Defensive patterns

Strategy: try-catch

Validate before calling

ConnectionManager::get('default')->query('SELECT 1'); // DB reachable & credentials valid before install step

Try / catch

try {
    $installer->installDatabase();
} catch (\Exception $e) {
    // inspect the real phinx error via CLI: bin/cake passbolt migrate
}

Prevention

Validate DB credentials and server version before starting the wizard.
Prefer CLI migrations where the underlying error is visible.
Clear stale migration locks after failed attempts.
Test migrations on a staging database with matching server versions.

When it happens

Trigger: Calling installDatabase() during the web installer database step when the Migrations migrate() call returns false, meaning a phinx migration aborted (SQL error, lock, bad connection config).

Common situations: Wrong DB credentials or host entered in the wizard's database form; DB user lacks privileges; unsupported database server version (old MySQL/MariaDB/Postgres); leftover phinx migration lock or partially applied migrations from a previous failed attempt.

Related errors

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

Appendix: source

Thrown at plugins/PassboltCe/WebInstaller/src/Utility/WebInstaller.php:290

        /** @var \App\Model\Table\UsersTable $Users */
        $Users = TableRegistry::getTableLocator()->get('Users');

        return $Users->findFirstAdmin()->get('id');
    }

    /**
     * Install database.
     *
     * @throws \Exception The database cannot be installed
     * @return void
     */
    public function installDatabase(): void
    {
        $migrations = new Migrations(['connection' => ConnectionManager::get('default')->configName()]);
        $migrated = $migrations->migrate();
        if (!$migrated) {
            throw new Exception(__('The database cannot be installed'));
        }
    }

    /**
     * Create the first user.
     *
     * @throws \App\Error\Exception\CustomValidationException There was a problem creating the first user
     * @throws \App\Error\Exception\CustomValidationException There was a problem creating the first user register token
     * @return void
     */
    public function createFirstUser(): void
    {
        $userData = $this->getSettings('first_user');
        if (empty($userData)) {
            return;
        }

        /** @var \App\Model\Table\UsersTable $Users */

View on GitHub (pinned to 31c1bbc10f)