{"record":{"id":"060d1c481812db0d","repo":"passbolt/passbolt_api","slug":"a-connection-could-not-be-established-with-the-credentials","errorCode":null,"errorMessage":"A connection could not be established with the credentials provided. Please verify the settings.","messagePattern":"A connection could not be established with the credentials provided\\. Please verify the settings\\.","errorType":"exception","errorClass":"CakeException","httpStatus":500,"severity":"error","filePath":"plugins/PassboltCe/WebInstaller/src/Controller/DatabaseController.php","lineNumber":185,"sourceCode":"        return $nbAdmins > 0;\n    }\n\n    /**\n     * Test the connection to the database\n     *\n     * @param array $data The database configuration to test\n     * @throws \\Cake\\Core\\Exception\\CakeException A connection could not be established with the provided data\n     * @return void\n     */\n    protected function testConnection(array $data): void\n    {\n        $config = DatabaseConfiguration::buildConfig($data);\n        $this->webInstaller->setSettings('database', $config);\n        $this->webInstaller->initDatabaseConnection();\n        if (!DatabaseConfiguration::testConnection()) {\n            $msg = __('A connection could not be established with the credentials provided.') . ' ';\n            $msg .= __('Please verify the settings.');\n            throw new CakeException($msg);\n        }\n    }\n\n    /**\n     * Validate data.\n     *\n     * @param array $data request data\n     * @throws \\Cake\\Core\\Exception\\CakeException The data does not validate\n     * @return array\n     */\n    protected function validateData(array $data): array\n    {\n        $form = new DatabaseConfigurationForm();\n        $this->set('formExecuteResult', $form);\n        if (!$form->execute($data)) {\n            throw new CakeException(__('The data entered are not correct'));\n        }\n        /** @var array $data */","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltCe/WebInstaller/src/Controller/DatabaseController.php#L167-L203","documentation":"DatabaseController::testConnection builds a config via DatabaseConfiguration::buildConfig, initializes the connection, and calls DatabaseConfiguration::testConnection(). If a connection cannot be made, it throws CakeException 'A connection could not be established with the credentials provided. Please verify the settings.' This is the WebInstaller's pre-flight DB connectivity check before writing config.","triggerScenarios":"The WebInstaller database step (indexPost -> testConnection) with an unreachable host/port, wrong database name, wrong username/password, or an unavailable database driver — testConnection() returns false.","commonSituations":"DB host entered as 'localhost' instead of the container service name (e.g. 'db' in ddev); MySQL/MariaDB not started; wrong port; DB user lacking privileges; Postgres vs MySQL confusion; firewall blocking the port.","solutions":["Verify host, port, database name, username and password by connecting manually (mysql -h <host> -u <user> -p or psql) with the exact values entered in the installer.","In containerized setups (Docker/ddev) use the internal service hostname (e.g. 'db'), not 'localhost' or '127.0.0.1'.","Confirm the database server is running and the port is reachable from the PHP container (nc -zv <host> <port>).","Create the database/user beforehand and grant privileges: CREATE DATABASE passbolt; GRANT ALL ON passbolt.* TO 'passbolt'@'%';"],"exampleFix":"// before (form data)\nhost: localhost, port: 3306  // inside a container, localhost is the PHP container itself\n// after\nhost: db, port: 3306, database: passbolt, username: passbolt, password: ****","handlingStrategy":"validation","validationCode":"// probe connectivity with the exact settings before submitting the installer form\nconst net = require('net');\nconst s = net.connect({ host, port }, () => { console.log('reachable'); s.end(); });\ns.on('error', (e) => { throw new Error('DB host unreachable: ' + e.message); });","typeGuard":"function isValidDbConfig(c) {\n  return c && typeof c.host === 'string' && c.host.length > 0 &&\n    Number.isInteger(Number(c.port)) && Number(c.port) > 0 &&\n    typeof c.database === 'string' && c.database.length > 0 &&\n    typeof c.username === 'string' && c.username.length > 0;\n}","tryCatchPattern":"try {\n  await post('/install/database', dbConfig);\n} catch (e) {\n  if (String(e.message).includes('A connection could not be established')) {\n    // verify host/port/credentials out-of-band, then retry\n  }\n  throw e;\n}","preventionTips":["In containers use the service hostname (e.g. 'db'), never 'localhost'.","Test credentials with a native client (mysql/psql) using identical values first.","Ensure the DB server is running and the port is open from the PHP host.","Create the database and grant the user privileges before running the installer."],"tags":["database","connection","webinstaller","mysql"],"backgroundTag":"connection-refused","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"}