Troubleshoot ownCloud 10 MySQL Connection Failures

When ownCloud 10 reports “Failed to connect to database,” first identify whether MySQL is unreachable, rejecting the account, or missing a PHP driver. Check the database service and the exact host, database name, and username saved in ownCloud’s config/config.php; then test those credentials from the ownCloud server before changing grants or recreating anything. This guide targets ownCloud Server 10.16 with MySQL or MariaDB. Menu labels and package commands can vary by operating system and installation method.

Know what the error is telling you

“Database connection failed” is a general message. The more specific MySQL or PHP error in the ownCloud log or web server log usually points to the cause. A connection error such as MySQL error 2002 or 2003 generally indicates a stopped service, wrong socket or port, blocked network path, or a server that is not listening where ownCloud expects. An “Access denied” message typically means MySQL received the connection but did not accept that username, password, or client host.

MySQL means the database server; MariaDB is a compatible database option supported by ownCloud. PDO MySQL is the PHP database driver that lets ownCloud communicate with either one. Action: note the exact error text and timestamp, then match it to the checks below rather than treating every connection failure as a bad password.

Prepare before changing settings

  • Confirm whether ownCloud and MySQL run on the same machine, different machines, or in separate containers.
  • Know the ownCloud installation path, database host, port or socket, database name, and dedicated database username.
  • Keep an administrator session or console access available. Back up config/config.php before editing it, and never post its database password in a support request.
  • Run commands as an administrator only where required. Replace example names and paths with values from your installation.

Do not delete or recreate the database as an initial troubleshooting step: existing user files and metadata depend on it. Action: make a verified backup of both the ownCloud data directory and database before making any database-level changes.

Check the database service and connection path

  1. Check that MySQL or MariaDB is running. On a systemd Linux host, inspect the service using the name installed on your system:
sudo systemctl status mysql
sudo systemctl status mariadb

One service name may not exist on your distribution. If the service is stopped, inspect its journal and database error log to find why before restarting it. Action: resolve startup errors such as a full disk or invalid database configuration before troubleshooting ownCloud credentials.

  1. Check the host and port from the ownCloud machine. Test TCP connectivity to the database host and port, commonly 3306. For a remote database, confirm name resolution, firewall rules, and that MySQL listens on an interface reachable from the ownCloud server. Do not expose port 3306 broadly to the internet.
  2. Understand the localhost socket difference. On Unix-like systems, a MySQL client that connects to localhost often uses a local Unix socket; 127.0.0.1 forces TCP. This matters when the database is local but PHP and MySQL use different socket paths. Action: compare the socket path and host setting with the database server’s actual configuration, or deliberately test TCP if that is the intended path.

Test login from the ownCloud server using the same database username, host, and database name that ownCloud uses:

mysql --protocol=TCP -h db.example.net -P 3306 -u oc_user -p owncloud

Enter the password at the prompt; do not put it directly in the command, where it may be saved in shell history. For a local socket connection, test the host and socket mode that match your configuration instead. A successful login proves that MySQL accepts that connection path and account, but it does not prove that PHP has its driver or that ownCloud is reading the same settings. Action: if this command fails, use the MySQL error to choose the next check.

Verify ownCloud settings, PHP driver, and privileges

ownCloud’s installation wizard writes the database type, database name, username, password, host, and table prefix in config/config.php. Review the values carefully without copying the password into logs or chat. The dbhost can include a host and port; if it says localhost, check whether the expected socket is available to the PHP process.

If the command-line client succeeds but ownCloud still fails, verify that the PHP runtime used by the web server has pdo_mysql installed and enabled. A shell command such as php -m only reports the CLI PHP runtime, which may differ from Apache or PHP-FPM. Action: inspect the active web PHP configuration and restart the relevant web/PHP service after enabling the extension.

For “Access denied,” check that MySQL has an account matching both the username and the client host seen by the database. MySQL treats accounts such as 'oc_user'@'localhost' and 'oc_user'@'10.0.0.5' as distinct. If the ownCloud app is in a container, the database may see a container or bridge address rather than localhost. Action: ask the database administrator to inspect the matching account and grants; grant access only from the ownCloud host or network that needs it.

Confirm that the database exists and that the ownCloud account can use it. Avoid granting global privileges or using the MySQL root account in ownCloud. The required permissions can depend on whether this is initial installation or an existing instance. Action: follow ownCloud’s database setup guidance for the specific stage, and do not change ownership or grants on unrelated databases.

Apply a correction and verify the fix

Correct only the setting that the tests identified: start the database service, use the reachable hostname and port, correct a socket mismatch, enable the PHP driver, fix the account password, or adjust a host-specific database grant. If you edit config/config.php, preserve valid PHP syntax and make a backup first. Do not change database name, table prefix, or credentials by guesswork.

After the change, reload ownCloud and confirm the page loads without the database connection warning. Check the ownCloud log for a successful request and make sure users can browse existing files. If MySQL reports “server has gone away” rather than a connection refusal, that is a different issue involving a dropped or timed-out connection or packet size; ownCloud documents MySQL timeout and packet-size settings for that case. Action: use the matching database troubleshooting guidance and change server limits only when logs support that diagnosis.

ownCloud’s current Server 10.16 documentation recommends the installation wizard for ordinary database setup and specifically calls out pdo_mysql and the MySQL socket path as checks. Exact package names, PHP versions, and service names depend on the host. Action: finish by repeating the connection test from the ownCloud server and confirming the application can read its existing data.

Official references

Leave a Comment

Troubleshoot ownCloud 10 MySQL Connection Failures

Find out whether MySQL, PHP, socket settings, or database permissions are blocking ownCloud 10, then verify a safe fix.

Set a Firm Expiration Limit for ownCloud Public Links

Set a Firm Expiration Limit for ownCloud Public Links

Make public link expiration mandatory in ownCloud Classic, set a maximum lifetime, and check existing shares that may need separate cleanup.

Add TOTP Two-Factor Login to ownCloud Infinite Scale with Keycloak

Add TOTP Two-Factor Login to ownCloud Infinite Scale with Keycloak

Enable TOTP through Keycloak, enroll users safely, and understand when Infinite Scale’s route-level MFA settings apply.

Restore ownCloud Sync by Matching the Client to Your Server

Check whether the issue is an OC10 and 7.x compatibility break or a damaged CSync journal, then apply the right fix without deleting synced files.

Put ownCloud on HTTPS with Let’s Encrypt and Nginx

Put ownCloud on HTTPS with Let’s Encrypt and Nginx

Choose HTTP-01 or DNS-01, configure an ownCloud reverse proxy, and verify Certbot renews HTTPS certificates automatically.

Connect ownCloud Infinite Scale to LDAP for User Sign-In

Configure oCIS LDAP sign-in, align user and group lookups, and verify TLS and schema settings before rollout.

Connect an S3 Bucket to ownCloud 10 as External Storage

Connect an S3 Bucket to ownCloud 10 as External Storage

Add an Amazon S3 bucket to ownCloud 10, prepare compatible credentials and endpoints, and check access without confusing a mount with primary storage.

Automate ownCloud Database Dumps with a Safe Nightly Cron Job

Automate ownCloud Database Dumps with a Safe Nightly Cron Job

Schedule protected MariaDB dumps for ownCloud Server, handle maintenance mode safely, and verify each backup before relying on it.

Move ownCloud Classic to oCIS with a Supported Migration

Plan an ownCloud 10 to oCIS migration with the supported app, ordered commands, identity checks, and a clear list of data that needs separate handling.

Brand ownCloud Classic 10 with a Theme App and CSS

Replace ownCloud Classic 10 logos and tune web UI colors with a theme app, while avoiding upgrade and integrity-check pitfalls.