MySQL database mysql database schema
Takeshi Mori Software Engineer

MySQL ERROR 1049: Unknown database 'X'

Encountering MySQL ERROR 1049: Unknown database 'X' means your MySQL server cannot find the specified database; this guide explains how to fix it with practical, engineer-tested steps.

What This Error Means

When you encounter MySQL ERROR 1049: Unknown database 'X', it signifies that your MySQL server successfully received a connection request and understood your intent to interact with a database named 'X', but it could not locate any database matching that specific name within its catalog. It's a clear statement from the server: "I know you want to talk to a database, but the one you asked for doesn't exist here." This error is distinct from connection refused errors (which mean the server isn't reachable) or authentication errors (which mean the server is there, the database might be there, but your credentials are bad). This error specifically points to a missing or misnamed database.

Why It Happens

From a technical perspective, this error occurs because the MySQL server, after a successful handshake with the client, performs a lookup for the specified database name. When this lookup yields no results, ERROR 1049 is returned. It's a fundamental check in the server's process. Think of it like trying to open a specific folder on your computer that simply isn't there. The operating system knows you want a folder, but it can't fulfill the request because the target doesn't exist by that name. In a database context, this usually stems from an inconsistency between what the application thinks the database name is, and what the MySQL server actually has registered.

Common Causes

In my experience, ERROR 1049 almost always boils down to one of a few common scenarios. These are usually simple to diagnose once you know where to look:

  1. Typo in Database Name: This is, by far, the most frequent culprit. A slight misspelling, an extra character, or a missing letter in the database name within your application's configuration or command-line arguments. For example, my_app_db instead of myapp_db.
  2. Database Not Yet Created: The database simply hasn't been created on the MySQL server instance you're connecting to. This is common in new setups, development environments, or after a database migration where the creation script might have been skipped.
  3. Incorrect Server Instance: You're connecting to the wrong MySQL server entirely. Perhaps you have multiple MySQL instances running locally, or your application is pointing to a staging database server when it should be pointing to development (or vice-versa). The correct database might exist on a different server.
  4. Case Sensitivity Mismatch: MySQL database names can be case-sensitive depending on the operating system and the lower_case_table_names server variable. If your application specifies MyDatabase but the actual database on a Linux server (with lower_case_table_names=0) is mydatabase, you'll hit this error. On macOS or Windows (where lower_case_table_names is often 1 or 2 by default), this might not be an issue, but it's crucial on production Linux environments.
  5. Schema vs. Database Confusion: While less common for this specific error, sometimes developers confuse "schema" with "database," especially coming from other database systems. MySQL uses "database" and "schema" interchangeably. If your connection string attempts to specify a database that is actually a table within another database, you might get unexpected behavior, though 1049 usually means the top-level identifier is missing.

Step-by-Step Fix

Here's a systematic approach I always follow to resolve ERROR 1049:

1. Verify the Database Name and Existence on the Server

First, log into your MySQL server using the command-line client or a GUI tool (like MySQL Workbench). Use the same credentials (user, host, port) your application is trying to use, if possible.

mysql -h localhost -u your_user -p

Once logged in, list all available databases:

SHOW DATABASES;

Carefully examine the output. Is the database you're looking for (X) present in the list? Pay extremely close attention to spelling and case. For example, if your application expects MyDatabase, but SHOW DATABASES; shows mydatabase, you've found a case sensitivity issue.

2. Check Your Application's Database Connection String/Configuration

Navigate to your application's configuration file or code where the database connection string is defined. This could be in:
* A .env file (e.g., DATABASE_URL=mysql://user:pass@host:port/X)
* A config.py, application.properties, database.yml, or similar file.
* Directly in your code if hardcoded (though this is bad practice, I've seen it!).

Locate the part that specifies the database name. Double-check it against the exact name you found in Step 1.

Example (Python with SQLAlchemy):

# In config.py or similar
SQLALCHEMY_DATABASE_URI = "mysql+pymysql://user:password@localhost:3306/your_actual_db_name"

Ensure your_actual_db_name precisely matches what SHOW DATABASES; returned.

3. Confirm MySQL Server Instance (Host and Port)

It's easy to connect to the wrong server, especially in local development with multiple Docker containers or local installations. Ensure your application's connection string points to the correct host and port of the MySQL instance where your database should exist.

# Example: Check if you're trying to connect to a different port or host
# mysql -h wrong_host -P 3307 -u your_user -p

The host (localhost, 127.0.0.1, a specific IP, or a Docker service name) and port (default 3306) must be correct.

4. Address Case Sensitivity (if applicable)

If you identified a case mismatch in Step 1, you have two primary options:
* Rename the database on the server: This can be complex and risky, especially in production.
* Adjust your application's configuration: Change the database name in your application to match the exact case of the database on the server. This is generally the safer and recommended approach.

For new setups, if you consistently face case sensitivity issues, consider setting lower_case_table_names=1 in your MySQL server configuration (my.cnf or my.ini) to make database and table names case-insensitive, but be aware this requires a server restart and needs careful consideration in existing environments.

5. Create the Database (if missing)

If Step 1 revealed that the database simply doesn't exist on the server, you need to create it.

CREATE DATABASE your_database_name;

Remember to grant appropriate permissions to the user your application is using if it's a new database and user:

GRANT ALL PRIVILEGES ON your_database_name.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

Replace your_database_name, your_user, and localhost with your actual values.

6. Restart Your Application

After making any changes to your application's configuration (Step 2 or 3) or creating the database (Step 5), ensure your application is restarted. Many frameworks and applications cache configuration settings and won't pick up changes until they are reloaded.

Code Examples

Here are some concise, copy-paste ready examples for various contexts:

Verifying Databases on CLI:

mysql -h localhost -P 3306 -u root -p # Connect to MySQL as root

(Enter password when prompted)

SHOW DATABASES; # List all databases

Creating a Database:

CREATE DATABASE my_application_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Python (SQLAlchemy URI):

# Example for a Flask application using SQLAlchemy
app.config["SQLALCHEMY_DATABASE_URI"] = "mysql+pymysql://user:password@127.0.0.1:3306/correct_db_name"

Java (JDBC URL):

String url = "jdbc:mysql://localhost:3306/your_actual_db?useSSL=false";
Connection conn = DriverManager.getConnection(url, "username", "password");

PHP (PDO Connection):

<?php
$dsn = 'mysql:host=localhost;dbname=your_actual_db;charset=utf8mb4';
try {
    $pdo = new PDO($dsn, 'username', 'password');
} catch (PDOException $e) {
    echo 'Connection failed: ' . $e->getMessage();
}
?>

Environment-Specific Notes

The ERROR 1049 can manifest slightly differently or have specific causes depending on your deployment environment.

  • Local Development: This is where I've seen ERROR 1049 most frequently due to simple human error: a developer forgetting to run the database migration script to create the database, or a local environment variable typo. When working with docker-compose.yml, ensure the MYSQL_DATABASE environment variable in your MySQL service matches what your application expects, and that your application uses the correct service name (e.g., db instead of localhost) for the host.
  • Docker: Within a Dockerized setup, the host in your connection string is usually the service name defined in your docker-compose.yml (e.g., db if your MySQL service is named db), not localhost. Additionally, ensure the MYSQL_DATABASE environment variable set for your MySQL container correctly defines the database your application needs. If it's not specified, MySQL might not create it automatically on first run.
  • Cloud (AWS RDS, GCP Cloud SQL, Azure Database for MySQL): When using managed database services, the endpoint (host) is crucial. It's usually a long hostname provided by the cloud provider (e.g., my-instance.xxxx.us-east-1.rds.amazonaws.com). Double-check this endpoint in your application's configuration. Also, verify that the database was indeed created in the cloud console or via a management tool, and that security groups or firewall rules allow your application's server to connect to the database instance on the correct port (typically 3306). I've seen cases where a new instance was provisioned, but the initial database was never explicitly created, leading to this error.

Frequently Asked Questions

Q: Is lower_case_table_names related to ERROR 1049?
A: Yes, absolutely. If your MySQL server has lower_case_table_names=0 (common on Linux) and your application requests MyDatabase but the actual database is named mydatabase (or vice-versa), MySQL will consider them different and return ERROR 1049 because it cannot find MyDatabase with that specific casing.

Q: I created the database, but I'm still getting ERROR 1049. What gives?
A: If you're certain the database exists and your application's configuration is correct, re-check that your application is connecting to the same MySQL server instance where you created the database. It's common to have multiple local MySQL installations or accidentally point to a development server instead of your local one. Also, remember to restart your application after creating the database.

Q: Does this error mean my MySQL server is down?
A: No, quite the opposite. ERROR 1049 means your application successfully connected to the MySQL server. If the server were down or unreachable, you would typically receive a different error message, such as Can't connect to MySQL server or a connection refused error, depending on your client library.

Q: Can user permissions cause ERROR 1049?
A: Not directly for ERROR 1049. This error specifically indicates the database name is "unknown" to the server. If it were a permissions issue, you would typically get an Access denied for user 'X'@'Y' to database 'Z' error (Error 1044 or 1045), assuming the database 'Z' did exist. However, if a user has very restricted permissions and can't even see databases, it could indirectly contribute to confusion, but 1049 almost always points to the database name itself.