passbolt/passbolt_api · error · CakeException

The database schema does not match the one expected

Error message

The database schema does not match the one expected

What it means

WebInstaller DatabaseConfiguration::validateSchema() compares the tables present in the database against the expected table list for schema version 1 and throws if any expected table is missing. It is the web installer's pre-install sanity check that the DB matches passbolt's expected schema.

Solutions

1. Check that the default datasource points at the intended database (config/app.php, app.local.php) and run bin/cake passbolt healthcheck.
2. Run migrations manually to see the underlying error: bin/cake passbolt migrate (or bin/cake migrations migrate) and fix the reported failure.
3. Verify the DB user has CREATE/ALTER privileges on the schema, then re-run migrations.
4. If the schema is intentionally different, restore a proper backup of the passbolt database instead of editing the expected table list.

$tables = $connection->getSchemaCollection()->listTables();
foreach (\Passbolt\WebInstaller\Utility\DatabaseConfiguration::getSchemaTables(1) as $t) {
    if (!in_array($t, $tables, true)) {
        // fix DB or run migrations before the installer check
    }
}

try {
    DatabaseConfiguration::validateSchema();
} catch (\Cake\Core\Exception\CakeException $e) {
    // fall back to CLI migration: bin/cake passbolt migrate
}

When it happens

Trigger: Calling validateSchema() (e.g. from the installer's hasAdmin / install check endpoints) when one or more tables returned by getSchemaTables(1) do not exist on the current default connection.

Common situations: Partial or failed migration run left an incomplete schema; the connection points to an empty or wrong database; the database user lacks privileges so only some tables were created; schema drift between passbolt versions.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Cleanup command cannot be executed on an instance having no…
• The database cannot be installed
• A connection could not be established with the credentials…
• 500
• An unexpected error occurred while creating the user in the…

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

Appendix: source

Thrown at plugins/PassboltCe/WebInstaller/src/Utility/DatabaseConfiguration.php:121

        /** @var \Cake\Database\Connection $connection */
        $connection = ConnectionManager::get('default');

        return $connection->getSchemaCollection()->listTables();
    }

    /**
     * Validate the database schema.
     *
     * @throws \Cake\Core\Exception\CakeException If the database schema does not validate
     * @return void
     */
    public static function validateSchema(): void
    {
        $tables = self::getTables();
        $expectedTables = self::getSchemaTables(1);
        foreach ($expectedTables as $expectedTable) {
            if (!in_array($expectedTable, $tables)) {
                throw new CakeException(__('The database schema does not match the one expected'));
            }
        }
    }

    /**
     * Get schema tables list. (per version number).
     *
     * @param int $version passbolt major version number.
     * @return array
     */
    public static function getSchemaTables(int $version = 2): array
    {
        // List of tables for passbolt v1.
        $tables = [
            'authentication_tokens',
            'avatars',
            'comments',
            'email_queue',

View on GitHub (pinned to 31c1bbc10f)