Laravel `artisan migrate` Error: `SQLSTATE[42S02]: Base table or view not found` on Ubuntu 20.04 LTS

Resolve the Laravel `SQLSTATE[42S02]` error during `artisan migrate` on Ubuntu 20.04 LTS. This guide covers database connection, permissions, caching, and Docker-related fixes.

This troubleshooting guide addresses a common Laravel error encountered when attempting to run database migrations, specifically "SQLSTATE[42S02]: Base table or view not found". This error typically indicates that Laravel cannot locate or access the expected database or a specific table within it, preventing successful schema evolution. It's a critical issue that halts development and deployment processes, often pointing to misconfigurations in database connectivity or permissions.

Symptom & Error Signature

When you execute the php artisan migrate command from your Laravel project's root directory, instead of a successful migration message, you will observe an error similar to the following in your terminal:

IlluminateDatabaseQueryException

SQLSTATE[42S02]: Base table or view not found: 1146 Table 'your_database.migrations' doesn't exist (SQL: select migration from migrations order by batch asc, migration asc)

at vendor/laravel/framework/src/Illuminate/Database/Connection.php:712 708| // If an exception occurs when attempting to run a query, we'll format the error 709| // message to include the bindings with the query, which will make debugging 710| // the data a lot easier if these errors tend to pop up a lot. 711| catch (Exception $e) { 712| throw new QueryException( 713| $query, $this->prepareBindings($bindings), $e 714| ); 715| } 716|

Exception trace:

1 PDOException::("SQLSTATE[42S02]: Base table or view not found: 1146 Table 'your_database.migrations' doesn't exist") vendor/laravel/framework/src/Illuminate/Database/Connection.php:547

2 PDOStatement::execute() vendor/laravel/framework/src/Illuminate/Database/Connection.php:547 `

The key parts of the error are SQLSTATE[42S02] and "Base table or view not found", often specifically mentioning the migrations table, or another table if you're running specific migrations on an existing, but possibly incomplete, database.

Root Cause Analysis

The SQLSTATE[42S02] error during artisan migrate fundamentally means Laravel couldn't find a table it expected to interact with. This can stem from several underlying issues:

1. Incorrect Database Configuration: The most frequent cause. The .env file contains incorrect credentials (DBHOST, DBPORT, DBDATABASE, DBUSERNAME, DB_PASSWORD), leading Laravel to attempt connection to a non-existent, wrong, or inaccessible database server/database schema.
2. Database Not Created: The database specified by DB_DATABASE in your .env file simply does not exist on your MySQL or PostgreSQL server. Laravel tries to connect to it but finds no such schema.
3. Insufficient Database User Permissions: The DBUSERNAME user specified in .env lacks the necessary privileges (e.g., CREATE, ALTER, DROP) to create tables in the specified DBDATABASE.
4. Configuration Cache Issues: Laravel caches its configuration for performance. If you've recently changed your .env file, especially database credentials, the cached configuration might still be pointing to old, invalid settings.
5. Missing PHP Database Extensions: The required PHP Data Objects (PDO) extension for your database type (e.g., php-mysql or php-pgsql) is not installed or enabled for your PHP version.
6. Incorrect Working Directory: The php artisan migrate command is executed from a directory other than your Laravel project root, causing it to fail to load the correct .env file or application context.
7. Docker/Containerization Issues: When running Laravel in Docker, the database service might not be properly linked, reachable, or its hostname/port is incorrectly configured within the Laravel container's .env. Persistent volumes for the database might also be missing or misconfigured, leading to data loss on container restarts.

Step-by-Step Resolution

Follow these steps sequentially to diagnose and resolve the SQLSTATE[42S02] error.

1. Verify Database Existence and Connectivity

First, confirm that the target database actually exists on your database server and that you can connect to it.

1. Check .env file: Open your Laravel project's .env file and note the DBCONNECTION, DBHOST, DBPORT, DBDATABASE, DBUSERNAME, and DBPASSWORD values.
2. `env
3. DB_CONNECTION=mysql # or pgsql
4. DB_HOST=127.0.0.1
5. DB_PORT=3306 # or 5432 for PostgreSQL
6. DBDATABASE=yourlaravel_db
7. DBUSERNAME=yourdb_user
8. DBPASSWORD=yourdb_password
9. `
10. Access your database server: Log in to your database server (e.g., via SSH to the machine hosting MySQL/PostgreSQL).
11. Check database existence:
12. * For MySQL:
13. `bash
14. mysql -u yourdbuser -p -h DBHOST -P DBPORT
15. # Enter yourdbpassword when prompted
16. SHOW DATABASES;
17. USE yourlaraveldb; # Attempt to select the database
18. `
19. * For PostgreSQL:
20. `bash
21. psql -U yourdbuser -h DBHOST -p DBPORT -d yourlaraveldb
22. # Enter yourdbpassword when prompted
23. l # List databases
24. c yourlaraveldb # Attempt to connect to the database
25. `
26. Create database if missing: If yourlaraveldb does not appear in the list of databases or you cannot connect to it, create it manually:
27. * For MySQL: (Login as root or a privileged user)
28. `bash
29. CREATE DATABASE yourlaraveldb CHARACTER SET utf8mb4 COLLATE utf8mb4unicodeci;
30. `
31. * For PostgreSQL: (Login as postgres or a privileged user)
32. `bash
33. CREATE DATABASE yourlaraveldb ENCODING 'UTF8' LCCOLLATE 'enUS.UTF-8' LCCTYPE 'enUS.UTF-8' TEMPLATE template0;
34. `
35. > [!IMPORTANT]
36. > Ensure that the DB_HOST is correctly set. 127.0.0.1 or localhost is common for local/same-server databases. If your database is on a different server, use its IP address or hostname.

2. Inspect and Correct .env Database Credentials

Even if the database exists, incorrect credentials will prevent Laravel from accessing it.

1. Re-verify .env: Double-check all database-related entries in your .env file against your actual database server configuration. Pay close attention to:
2. * DB_HOST: Should be the IP or hostname of the database server.
3. * DB_PORT: Default is 3306 for MySQL, 5432 for PostgreSQL.
4. * DB_DATABASE: The exact name of the database.
5. * DBUSERNAME: The username with access to DBDATABASE.
6. * DBPASSWORD: The password for DBUSERNAME.
7. * > [!WARNING] Ensure that passwords or usernames containing special characters (like #, $, !) are correctly escaped or quoted in your .env file if necessary, though Laravel generally handles this well. For robust passwords, consider avoiding some shell-special characters.

1. Test connection with correct details: Attempt to connect to the database again using the exact values from your .env file, as shown in Step 1.

3. Ensure Database User Privileges

The DBUSERNAME user must have sufficient permissions to create, alter, and drop tables within yourlaravel_db.

1. Login to your database server as a privileged user: For example, as root for MySQL or postgres for PostgreSQL.
2. Grant permissions:
3. * For MySQL:
4. `sql
5. — If the user doesn't exist, create it first
6. CREATE USER 'yourdbuser'@'DBHOST' IDENTIFIED BY 'yourdb_password';
7. — Grant all privileges on yourlaraveldb to the user
8. GRANT ALL PRIVILEGES ON yourlaraveldb.* TO 'yourdbuser'@'DB_HOST';
9. FLUSH PRIVILEGES;
10. `
11. Replace DB_HOST with localhost, 127.0.0.1, or % (for any host – use with caution in production).
12. * For PostgreSQL:
13. `sql
14. — Connect to the postgres default database
15. c postgres
16. — If the user doesn't exist, create it first
17. CREATE USER yourdbuser WITH PASSWORD 'yourdbpassword';
18. — Grant all privileges on yourlaraveldb to the user
19. GRANT ALL PRIVILEGES ON DATABASE yourlaraveldb TO yourdbuser;
20. `
21. > [!WARNING]
22. > Granting ALL PRIVILEGES is common for development. In production, consider granting only the minimum necessary privileges (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX, REFERENCES) for better security.

4. Clear Laravel Configuration Cache

Laravel caches configuration files to speed up application loading. If you've recently modified .env, the cached version might be stale.

1. Navigate to your Laravel project root:
2. `bash
3. cd /var/www/html/yourlaravelapp
4. `
5. Clear caches:
6. `bash
7. php artisan config:clear
8. php artisan cache:clear
9. php artisan view:clear
10. # For Laravel 8+
11. php artisan optimize:clear
12. `
13. Attempt migration again:
14. `bash
15. php artisan migrate
16. `

5. Install Missing PHP Database Extensions

Laravel relies on PHP's PDO extensions to communicate with databases. If these are missing, connections will fail.

1. Identify your PHP version:
2. `bash
3. php -v
4. `
5. (e.g., PHP 7.4.3 or PHP 8.1.10)
6. Install the correct PDO extension:
7. * For MySQL:
8. `bash
9. sudo apt update
10. sudo apt install php7.4-mysql # Replace 7.4 with your PHP version (e.g., php8.1-mysql)
11. `
12. * For PostgreSQL:
13. `bash
14. sudo apt update
15. sudo apt install php7.4-pgsql # Replace 7.4 with your PHP version (e.g., php8.1-pgsql)
16. `
17. Restart PHP-FPM or Apache:
18. * For Nginx with PHP-FPM:
19. `bash
20. sudo systemctl restart php7.4-fpm.service # Adjust service name for your PHP version
21. `
22. * For Apache:
23. `bash
24. sudo systemctl restart apache2.service
25. `
26. Verify extension: You can check if the extension is loaded:
27. `bash
28. php -m | grep pdomysql # or pdopgsql
29. `
30. It should output pdomysql or pdopgsql.

6. Check File Permissions

Incorrect file permissions on Laravel's storage and bootstrap/cache directories can prevent it from writing necessary files, sometimes leading to unexpected errors.

1. Navigate to your Laravel project root:
2. `bash
3. cd /var/www/html/yourlaravelapp
4. `
5. Set correct ownership and permissions: Assuming your web server user is www-data (common on Ubuntu) and your application root is /var/www/html/yourlaravelapp:
6. `bash
7. sudo chown -R www-data:www-data /var/www/html/yourlaravelapp
8. sudo find /var/www/html/yourlaravelapp -type d -exec chmod 755 {} ;
9. sudo find /var/www/html/yourlaravelapp -type f -exec chmod 644 {} ;
10. sudo chmod -R 775 /var/www/html/yourlaravelapp/storage
11. sudo chmod -R 775 /var/www/html/yourlaravelapp/bootstrap/cache
12. `
13. > [!IMPORTANT]
14. > The storage and bootstrap/cache directories, along with their contents, must be writable by the web server user. If you use a different user/group for your web server (e.g., a custom FPM pool user), adjust www-data accordingly.

7. If Using Docker/Docker Compose

When deploying with Docker, network connectivity and service naming are critical.

1. Verify service names and network:
2. * Open your docker-compose.yml file.
3. * Ensure the DB_HOST in your Laravel container's .env (or environment variables in docker-compose.yml) matches the service name of your database container (e.g., db or mysql).
4. * Example docker-compose.yml snippet:
5. `yaml
6. services:
7. app:
8. build: .
9. environment:
10. DB_HOST: db # This MUST match the database service name below
11. DBDATABASE: yourlaravel_db
12. DBUSERNAME: yourdb_user
13. DBPASSWORD: yourdb_password
14. depends_on:
15. – db
16. db:
17. image: mysql:8.0 # or postgres:12
18. environment:
19. MYSQLDATABASE: yourlaravel_db
20. MYSQLUSER: yourdb_user
21. MYSQLPASSWORD: yourdb_password
22. MYSQLROOTPASSWORD: root_password
23. volumes:
24. – db_data:/var/lib/mysql
25. volumes:
26. db_data:
27. `
28. Check database container status:
29. `bash
30. docker-compose ps
31. `
32. Ensure your database service (db or mysql) is Up.
33. Test connectivity from inside the Laravel container:
34. `bash
35. docker exec -it <yourlaravelappcontainername> bash
36. php artisan tinker
37. `
38. Inside tinker, try to connect:
39. `php
40. DB::connection()->getPdo();
41. `
42. If successful, it should return a PDO object. If it throws an error, it indicates a connectivity issue from within the container.
43. Rebuild and restart: Sometimes, container network issues can persist. A full rebuild and restart can help:
44. `bash
45. docker-compose down –volumes
46. docker-compose up –build -d
47. `
48. Then, attempt php artisan migrate from within the Laravel container:
49. `bash
50. docker exec -it <yourlaravelappcontainername> php artisan migrate
51. `

8. Verify Laravel Application Path

Ensure you are executing php artisan migrate from the root directory of your Laravel project, where the artisan script and .env file are located.

1. Check current directory:
2. `bash
3. pwd
4. `
5. List files:
6. `bash
7. ls -F
8. `
9. You should see artisan, .env, app/, bootstrap/, config/, etc. If not, cd into the correct directory.

After performing these steps, re-run php artisan migrate. If the issue persists, carefully review your terminal output for any new error messages that might point to a different problem.