{"record":{"id":"fe73cb5c0321a522","repo":"passbolt/passbolt_api","slug":"cleanup-command-cannot-be-executed-on-an-instance-having-no","errorCode":null,"errorMessage":"Cleanup command cannot be executed on an instance having no users table.","messagePattern":"Cleanup command cannot be executed on an instance having no users table\\.","errorType":"console","errorClass":"InternalErrorException","httpStatus":500,"severity":"error","filePath":"src/Command/CleanupCommand.php","lineNumber":221,"sourceCode":"        }\n\n        return $this->successCode();\n    }\n\n    /**\n     * Runs series of checks to make sure database is in valid state to run the cleanup command.\n     *\n     * @return void\n     * @throws \\Cake\\Http\\Exception\\InternalErrorException If database is not in valid state.\n     */\n    private function assertDatabaseState(): void\n    {\n        // Check 1. Users table exist in db\n        /** @var \\Cake\\Database\\Connection $connection */\n        $connection = ConnectionManager::get('default');\n        $listTables = $connection->getSchemaCollection()->listTables();\n        if (!in_array('users', $listTables)) {\n            throw new InternalErrorException(\n                __('Cleanup command cannot be executed on an instance having no users table.')\n            );\n        }\n\n        // Check 2. Atleast one active administrator is present\n        $admin = $this->Users->findFirstAdmin();\n        if (is_null($admin)) {\n            throw new InternalErrorException(\n                __('Cleanup command cannot be executed on an instance having no active administrator.')\n            );\n        }\n    }\n\n    /**\n     * Convert the method name to a human readeable string. eg. \"cleanupMethodName\" become \"Method Name\".\n     *\n     * @param string $methodName Method name\n     * @return string","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/src/Command/CleanupCommand.php#L203-L239","documentation":"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.","triggerScenarios":"Running `passbolt cleanup` against a default connection whose schema lacks a `users` table — detected via ConnectionManager::get('default')->getSchemaCollection()->listTables().","commonSituations":"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.","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."],"exampleFix":"// before: cleanup on an empty DB\n$ passbolt cleanup\n\n// after: migrate first, then cleanup\n$ passbolt migrate\n$ passbolt cleanup","handlingStrategy":"validation","validationCode":"$tables = ConnectionManager::get('default')\n    ->getSchemaCollection()->listTables();\nif (!in_array('users', $tables, true)) {\n    // run migrations first: bin/cake migrations migrate\n    exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n    $this->Cleanup->run();\n} catch (InternalErrorException $e) {\n    // message mentions missing users table => run `passbolt migrate` and retry\n}","preventionTips":["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."],"tags":["database","schema","cli","migrations","precondition"],"backgroundTag":"schema-validation-failed","analyzedSha":"31c1bbc10f32808a607fa9bd81891e898779c0bc","analyzedAt":"2026-09-17T00:04:38.960Z","contentChangedAt":"2026-09-17T00:04:38.960Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}