Troubleshooting Database Connection Issues

Craft requires a healthy database connection, and the following pointers may help identify and fix common connection issues.

Troubleshooting a “Craft can’t connect” error #

Trouble connecting to your database may result in one of the following errors:

Craft CMS can’t connect to the database with the credentials in config/db.php

Craft can’t connect to the database. Check your connection settings.

Start by checking the contents of config/db.php, which should indicate what environment variables Craft is checking for its database connection settings. Generally, that file should look something like this and it may be a good idea to update yours if it doesn’t.

If another developer has customized config/db.php or introduced additional parts to it, you may need to follow their setup instructions instead.

Is Craft getting database settings? #

It’s possible you’ve specified database settings Craft is unable to see.

• Did you provide the correct settings during the install process?
  Double check the setting names in addition to the values. Providing the right value for DB_HOST rather than DB_SERVER, for example, would look reasonable but still cause an error.
• Did you try re-entering the credentials?
  Run php craft setup/db-creds and verify that your settings were saved to .env in your project root.
• Is the phpdotenv library installed?
  If you’re using .env, Craft needs vlucas/phpdotenv in order to read it. Make sure that dependency is listed in composer.json and installed.
• Is your web server setting environment constants?
  If you’ve set environment variables in your web server instead of .env, run php -i | grep DB_ and verify they’re present. If not, you may need to adjust your web server.
• Is Craft trying to use the values you provided?
  If you’re comfortable using Xdebug, you can take a look directly at the connection values Craft is using during a request:
  1. In web/index.php, set a breakpoint on $app->run().
  2. Load any page from the site in your browser.
  3. In your debugger variables, navigate to $app → *yii\di\ServiceLocator*_components → db and look for the dsn, username, and password attributes. Craft builds the DSN string regardless of how you provided your settings, and the values present here are what Craft is ultimately trying to use for the connection. Any missing or unexpected settings may help narrow the issue.

Are your database settings correct? #

If you’ve confirmed that Craft is trying to use the settings you provided, you’ll want to ensure those settings are accurate.

• Can you verify the settings with a standalone test script?
  If so, that could point to something Craft-specific. You can download, edit, and run this standalone PHP script for a quick test of your settings.
• Did you provide settings that work from your local machine but not in Craft’s environment?
  If Craft is running inside a container (Nitro, Docker, etc.), the settings you use to connect to the database outside the container will likely differ from those Craft uses inside the container. Double-check your settings to ensure they’re meant to be used by PHP.
• Do you have conflicting database settings?
  Craft’s config/db.php can use settings provided in your server’s environment constants, a .env file, or directly entered into config/db.php—in that order. (But don’t write your database settings directly into config/db.php if you can help it!) Be sure you haven’t provided settings more than once that could be in conflict. Also know that a DB_DSN string will override settings you otherwise specify for DB_DRIVER, DB_SERVER, DB_DATABASE, and DB_PORT.

Troubleshooting a surprise install prompt #

When Craft has a valid database connection and doesn’t find data from an existing install, it will prompt you to begin the installation process.

If you’re seeing the install screen where you were expecting to log in to the control panel, Craft isn’t finding your project data. In this case there are a few things to check:

• Did you successfully import a database from another project?
  Once you’ve imported project data, you should be able to browse it from a tool like Sequel Pro, TablePlus, or phpMyAdmin. The database should have all the same tables as the original source, and if not you should re-export and re-import since incomplete data could cause other problems.
• Is there a table prefix mismatch?
  If you imported data from an environment that includes a table prefix and forgot to add it to your settings (or vice-versa), you’ll need to adjust your settings so DB_TABLE_PREFIX is consistent. If you see this error message in your terminal, it’s likely this is your problem:

  Craft can’t fetch the craft_info table row.
  Exception: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'craft3.craft_info' doesn't exist

As a last-ditch effort, you can complete the install process and try to find where the new tables went. That should at least indicate what Craft has connected to and where it’s able to store database information.