passbolt/passbolt_api · error · InternalErrorException

Cleanup command cannot be executed on an instance having no…

Error message

Cleanup command cannot be executed on an instance having no users table.

What it means

Thrown by CleanupCommand::assertDatabaseState() as a pre-flight guard: the passbolt cleanup command repairs referential integrity and refuses to run if the `users` table does not exist in the default database connection. Without it, most consistency checks (e.g. finding an active admin) would fail nonsensically. Reported as InternalErrorException.

Solutions

Run `passbolt migrate` (or bin/cake migrations migrate) to create the base schema, then re-run cleanup.
Verify DATASOURCES_DEFAULT_* env/config actually points to the passbolt database (list tables manually: mysql -e 'show tables' or \dt in psql).
Restore the missing users table from a backup if the database was partially wiped, then re-run migrations to catch up.
Re-run `passbolt healthcheck` after fixing the schema to confirm the installation state is consistent.

Example fix

// before: cleanup on an empty DB
$ passbolt cleanup

// after: migrate first, then cleanup
$ passbolt migrate
$ passbolt cleanup

Defensive patterns

Strategy: validation

Validate before calling

$tables = ConnectionManager::get('default')
    ->getSchemaCollection()->listTables();
if (!in_array('users', $tables, true)) {
    // run migrations first: bin/cake migrations migrate
    exit(1);
}

Try / catch

try {
    $this->Cleanup->run();
} catch (InternalErrorException $e) {
    // message mentions missing users table => run `passbolt migrate` and retry
}

Prevention

Always run `passbolt migrate` after deployments and before `passbolt cleanup`.
Verify datasource env vars point to the passbolt database in every environment (check with a `show tables` query).
Take full schema+data backups; verify restores include core tables before running repair commands.
Include `passbolt healthcheck` in CI/post-deploy checks to catch missing-schema states early.

When it happens

Trigger: Running `passbolt cleanup` against a default connection whose schema lacks a `users` table — detected via ConnectionManager::get('default')->getSchemaCollection()->listTables().

Common situations: Database migrations never ran (fresh empty database); connection pointing to the wrong database/schema (wrong DATASOURCES env vars, wrong Postgres search_path or MySQL database name); partial restore that skipped core tables; typo in datasource credentials connecting to an unrelated database.

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

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

Appendix: source

Thrown at src/Command/CleanupCommand.php:221

        }

        return $this->successCode();
    }

    /**
     * Runs series of checks to make sure database is in valid state to run the cleanup command.
     *
     * @return void
     * @throws \Cake\Http\Exception\InternalErrorException If database is not in valid state.
     */
    private function assertDatabaseState(): void
    {
        // Check 1. Users table exist in db
        /** @var \Cake\Database\Connection $connection */
        $connection = ConnectionManager::get('default');
        $listTables = $connection->getSchemaCollection()->listTables();
        if (!in_array('users', $listTables)) {
            throw new InternalErrorException(
                __('Cleanup command cannot be executed on an instance having no users table.')
            );
        }

        // Check 2. Atleast one active administrator is present
        $admin = $this->Users->findFirstAdmin();
        if (is_null($admin)) {
            throw new InternalErrorException(
                __('Cleanup command cannot be executed on an instance having no active administrator.')
            );
        }
    }

    /**
     * Convert the method name to a human readeable string. eg. "cleanupMethodName" become "Method Name".
     *
     * @param string $methodName Method name
     * @return string

View on GitHub (pinned to 31c1bbc10f)