{"id":56,"date":"2026-07-14T00:00:00","date_gmt":"2026-07-14T00:00:00","guid":{"rendered":"http:\/\/\/var\/www\/html\/?p=56"},"modified":"2026-07-21T01:02:32","modified_gmt":"2026-07-21T01:02:32","slug":"laravel-artisan-migrate-sqlstate-base-table-or-view-not-found-on-ubuntu-2004-lts","status":"publish","type":"post","link":"https:\/\/butitworkedlocal.com\/laravel-artisan-migrate-sqlstate-base-table-or-view-not-found-on-ubuntu-2004-lts\/","title":{"rendered":"Laravel `artisan migrate` Error: `SQLSTATE[42S02]: Base table or view not found` on Ubuntu 20.04 LTS"},"content":{"rendered":"\n

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.<\/strong><\/p>\n\n\n

This troubleshooting guide addresses a common Laravel error encountered when attempting to run database migrations, specifically "SQLSTATE[42S02]: Base table or view not found<\/code>". 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.<\/p>\n

Symptom & Error Signature<\/h3>\n

When you execute the php artisan migrate<\/code> 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:<\/p>\n

php artisan migrate\n\n   IlluminateDatabaseQueryException\n\n  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)\n\n  at vendor\/laravel\/framework\/src\/Illuminate\/Database\/Connection.php:712\n    708|         \/\/ If an exception occurs when attempting to run a query, we'll format the error\n    709|         \/\/ message to include the bindings with the query, which will make debugging\n    710|         \/\/ the data a lot easier if these errors tend to pop up a lot.\n    711|         catch (Exception $e) {\n    712|             throw new QueryException(\n    713|                 $query, $this->prepareBindings($bindings), $e\n    714|             );\n    715|         }\n    716|\n\n  Exception trace:\n\n  1   PDOException::("SQLSTATE[42S02]: Base table or view not found: 1146 Table 'your_database.migrations' doesn't exist")\n      vendor\/laravel\/framework\/src\/Illuminate\/Database\/Connection.php:547\n\n  2   PDOStatement::execute()\n      vendor\/laravel\/framework\/src\/Illuminate\/Database\/Connection.php:547\n<\/code><\/pre>\n
The key parts of the error are SQLSTATE[42S02]<\/code> and "Base table or view not found<\/code>", often specifically mentioning the migrations<\/code> table, or another table if you're running specific migrations on an existing, but possibly incomplete, database.<\/p>\n
Root Cause Analysis<\/h3>\n
The SQLSTATE[42S02]<\/code> error during artisan migrate<\/code> fundamentally means Laravel couldn't find a table it expected to interact with. This can stem from several underlying issues:<\/p>\n
    \n
  1. Incorrect Database Configuration<\/strong>: The most frequent cause. The .env<\/code> file contains incorrect credentials (DB_HOST<\/code>, DB_PORT<\/code>, DB_DATABASE<\/code>, DB_USERNAME<\/code>, DB_PASSWORD<\/code>), leading Laravel to attempt connection to a non-existent, wrong, or inaccessible database server\/database schema.<\/li>\n
  2. Database Not Created<\/strong>: The database specified by DB_DATABASE<\/code> in your .env<\/code> file simply does not exist on your MySQL or PostgreSQL server. Laravel tries to connect to it but finds no such schema.<\/li>\n
  3. Insufficient Database User Permissions<\/strong>: The DB_USERNAME<\/code> user specified in .env<\/code> lacks the necessary privileges (e.g., CREATE<\/code>, ALTER<\/code>, DROP<\/code>) to create tables in the specified DB_DATABASE<\/code>.<\/li>\n
  4. Configuration Cache Issues<\/strong>: Laravel caches its configuration for performance. If you've recently changed your .env<\/code> file, especially database credentials, the cached configuration might still be pointing to old, invalid settings.<\/li>\n
  5. Missing PHP Database Extensions<\/strong>: The required PHP Data Objects (PDO) extension for your database type (e.g., php-mysql<\/code> or php-pgsql<\/code>) is not installed or enabled for your PHP version.<\/li>\n
  6. Incorrect Working Directory<\/strong>: The php artisan migrate<\/code> command is executed from a directory other than your Laravel project root, causing it to fail to load the correct .env<\/code> file or application context.<\/li>\n
  7. Docker\/Containerization Issues<\/strong>: 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<\/code>. Persistent volumes for the database might also be missing or misconfigured, leading to data loss on container restarts.<\/li>\n<\/ol>\n
    Step-by-Step Resolution<\/h3>\n
    Follow these steps sequentially to diagnose and resolve the SQLSTATE[42S02]<\/code> error.<\/p>\n
    1. Verify Database Existence and Connectivity<\/h4>\n
    First, confirm that the target database actually exists on your database server and that you can connect to it.<\/p>\n
      \n
    1. Check .env<\/code> file<\/strong>: Open your Laravel project's .env<\/code> file and note the DB_CONNECTION<\/code>, DB_HOST<\/code>, DB_PORT<\/code>, DB_DATABASE<\/code>, DB_USERNAME<\/code>, and DB_PASSWORD<\/code> values.
      DB_CONNECTION=mysql # or pgsql\nDB_HOST=127.0.0.1\nDB_PORT=3306 # or 5432 for PostgreSQL\nDB_DATABASE=your_laravel_db\nDB_USERNAME=your_db_user\nDB_PASSWORD=your_db_password\n<\/code><\/pre>\n<\/li>\n
    2. Access your database server<\/strong>: Log in to your database server (e.g., via SSH to the machine hosting MySQL\/PostgreSQL).<\/li>\n
    3. Check database existence<\/strong>:
        \n
      • For MySQL<\/strong>:
        mysql -u your_db_user -p -h DB_HOST -P DB_PORT\n# Enter your_db_password when prompted\nSHOW DATABASES;\nUSE your_laravel_db; # Attempt to select the database\n<\/code><\/pre>\n<\/li>\n
      • For PostgreSQL<\/strong>:
        psql -U your_db_user -h DB_HOST -p DB_PORT -d your_laravel_db\n# Enter your_db_password when prompted\nl # List databases\nc your_laravel_db # Attempt to connect to the database\n<\/code><\/pre>\n<\/li>\n<\/ul>\n<\/li>\n
      • Create database if missing<\/strong>: If your_laravel_db<\/code> does not appear in the list of databases or you cannot connect to it, create it manually:
          \n
        • For MySQL<\/strong>: (Login as root or a privileged user)
          CREATE DATABASE your_laravel_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n<\/code><\/pre>\n<\/li>\n
        • For PostgreSQL<\/strong>: (Login as postgres or a privileged user)
          CREATE DATABASE your_laravel_db ENCODING 'UTF8' LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0;\n<\/code><\/pre>\n<\/li>\n<\/ul>\n
          Ensure that the DB_HOST<\/code> is correctly set. 127.0.0.1<\/code> or localhost<\/code> is common for local\/same-server databases. If your database is on a different server, use its IP address or hostname.<\/p>\n<\/blockquote>\n<\/li>\n<\/ol>\n
          2. Inspect and Correct .env<\/code> Database Credentials<\/h4>\n
          Even if the database exists, incorrect credentials will prevent Laravel from accessing it.<\/p>\n
            \n
          1. Re-verify .env<\/code><\/strong>: Double-check all<\/em> database-related entries in your .env<\/code> file against your actual database server configuration. Pay close attention to:<\/p>\n
              \n
            • DB_HOST<\/code>: Should be the IP or hostname of the database server.<\/li>\n
            • DB_PORT<\/code>: Default is 3306<\/code> for MySQL, 5432<\/code> for PostgreSQL.<\/li>\n
            • DB_DATABASE<\/code>: The exact name of the database.<\/li>\n
            • DB_USERNAME<\/code>: The username with access to DB_DATABASE<\/code>.<\/li>\n
            • DB_PASSWORD<\/code>: The password for DB_USERNAME<\/code>.<\/li>\n
            • > [!WARNING]<\/code> Ensure that passwords or usernames containing special characters (like #<\/code>, $<\/code>, !<\/code>) are correctly escaped or quoted in your .env<\/code> file if necessary, though Laravel generally handles this well. For robust passwords, consider avoiding some shell-special characters.<\/li>\n<\/ul>\n<\/li>\n
            • Test connection with correct details<\/strong>: Attempt to connect to the database again using the exact values from your .env<\/code> file, as shown in Step 1.<\/p>\n<\/li>\n<\/ol>\n
              3. Ensure Database User Privileges<\/h4>\n
              The DB_USERNAME<\/code> user must have sufficient permissions to create, alter, and drop tables within your_laravel_db<\/code>.<\/p>\n
                \n
              1. Login to your database server as a privileged user<\/strong>: For example, as root<\/code> for MySQL or postgres<\/code> for PostgreSQL.<\/li>\n
              2. Grant permissions<\/strong>:
                  \n
                • For MySQL<\/strong>:
                  -- If the user doesn't exist, create it first\nCREATE USER 'your_db_user'@'DB_HOST' IDENTIFIED BY 'your_db_password';\n-- Grant all privileges on your_laravel_db to the user\nGRANT ALL PRIVILEGES ON your_laravel_db.* TO 'your_db_user'@'DB_HOST';\nFLUSH PRIVILEGES;\n<\/code><\/pre>\nReplace DB_HOST<\/code> with localhost<\/code>, 127.0.0.1<\/code>, or %<\/code> (for any host – use with caution in production).<\/li>\n
                • For PostgreSQL<\/strong>:
                  -- Connect to the postgres default database\nc postgres\n-- If the user doesn't exist, create it first\nCREATE USER your_db_user WITH PASSWORD 'your_db_password';\n-- Grant all privileges on your_laravel_db to the user\nGRANT ALL PRIVILEGES ON DATABASE your_laravel_db TO your_db_user;\n<\/code><\/pre>\n<\/li>\n<\/ul>\n
                  Granting ALL PRIVILEGES<\/code> is common for development. In production, consider granting only the minimum necessary privileges (SELECT<\/code>, INSERT<\/code>, UPDATE<\/code>, DELETE<\/code>, CREATE<\/code>, ALTER<\/code>, DROP<\/code>, INDEX<\/code>, REFERENCES<\/code>) for better security.<\/p>\n<\/blockquote>\n<\/li>\n<\/ol>\n
                  4. Clear Laravel Configuration Cache<\/h4>\n
                  Laravel caches configuration files to speed up application loading. If you've recently modified .env<\/code>, the cached version might be stale.<\/p>\n
                    \n
                  1. Navigate to your Laravel project root<\/strong>:
                    cd \/var\/www\/html\/your_laravel_app\n<\/code><\/pre>\n<\/li>\n
                  2. Clear caches<\/strong>:
                    php artisan config:clear\nphp artisan cache:clear\nphp artisan view:clear\n# For Laravel 8+\nphp artisan optimize:clear\n<\/code><\/pre>\n<\/li>\n
                  3. Attempt migration again<\/strong>:
                    php artisan migrate\n<\/code><\/pre>\n<\/li>\n<\/ol>\n
                    5. Install Missing PHP Database Extensions<\/h4>\n
                    Laravel relies on PHP's PDO extensions to communicate with databases. If these are missing, connections will fail.<\/p>\n
                      \n
                    1. Identify your PHP version<\/strong>:
                      php -v\n<\/code><\/pre>\n(e.g., PHP 7.4.3<\/code> or PHP 8.1.10<\/code>)<\/li>\n
                    2. Install the correct PDO extension<\/strong>:
                        \n
                      • For MySQL<\/strong>:
                        sudo apt update\nsudo apt install php7.4-mysql # Replace 7.4 with your PHP version (e.g., php8.1-mysql)\n<\/code><\/pre>\n<\/li>\n
                      • For PostgreSQL<\/strong>:
                        sudo apt update\nsudo apt install php7.4-pgsql # Replace 7.4 with your PHP version (e.g., php8.1-pgsql)\n<\/code><\/pre>\n<\/li>\n<\/ul>\n<\/li>\n
                      • Restart PHP-FPM or Apache<\/strong>:
                          \n
                        • For Nginx with PHP-FPM<\/strong>:
                          sudo systemctl restart php7.4-fpm.service # Adjust service name for your PHP version\n<\/code><\/pre>\n<\/li>\n
                        • For Apache<\/strong>:
                          sudo systemctl restart apache2.service\n<\/code><\/pre>\n<\/li>\n<\/ul>\n<\/li>\n
                        • Verify extension<\/strong>: You can check if the extension is loaded:
                          php -m | grep pdo_mysql # or pdo_pgsql\n<\/code><\/pre>\nIt should output pdo_mysql<\/code> or pdo_pgsql<\/code>.<\/li>\n<\/ol>\n
                          6. Check File Permissions<\/h4>\n
                          Incorrect file permissions on Laravel's storage<\/code> and bootstrap\/cache<\/code> directories can prevent it from writing necessary files, sometimes leading to unexpected errors.<\/p>\n
                            \n
                          1. Navigate to your Laravel project root<\/strong>:
                            cd \/var\/www\/html\/your_laravel_app\n<\/code><\/pre>\n<\/li>\n
                          2. Set correct ownership and permissions<\/strong>: Assuming your web server user is www-data<\/code> (common on Ubuntu) and your application root is \/var\/www\/html\/your_laravel_app<\/code>:
                            sudo chown -R www-data:www-data \/var\/www\/html\/your_laravel_app\nsudo find \/var\/www\/html\/your_laravel_app -type d -exec chmod 755 {} ;\nsudo find \/var\/www\/html\/your_laravel_app -type f -exec chmod 644 {} ;\nsudo chmod -R 775 \/var\/www\/html\/your_laravel_app\/storage\nsudo chmod -R 775 \/var\/www\/html\/your_laravel_app\/bootstrap\/cache\n<\/code><\/pre>\n
                            The storage<\/code> and bootstrap\/cache<\/code> directories, along with their contents, must<\/em> 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<\/code> accordingly.<\/p>\n<\/blockquote>\n<\/li>\n<\/ol>\n
                            7. If Using Docker\/Docker Compose<\/h4>\n
                            When deploying with Docker, network connectivity and service naming are critical.<\/p>\n
                              \n
                            1. Verify service names and network<\/strong>:
                                \n
                              • Open your docker-compose.yml<\/code> file.<\/li>\n
                              • Ensure the DB_HOST<\/code> in your Laravel container's .env<\/code> (or environment variables in docker-compose.yml<\/code>) matches the service name of your database container (e.g., db<\/code> or mysql<\/code>).<\/li>\n
                              • Example docker-compose.yml<\/code> snippet:
                                services:\n  app:\n    build: .\n    environment:\n      DB_HOST: db # This MUST match the database service name below\n      DB_DATABASE: your_laravel_db\n      DB_USERNAME: your_db_user\n      DB_PASSWORD: your_db_password\n    depends_on:\n      - db\n  db:\n    image: mysql:8.0 # or postgres:12\n    environment:\n      MYSQL_DATABASE: your_laravel_db\n      MYSQL_USER: your_db_user\n      MYSQL_PASSWORD: your_db_password\n      MYSQL_ROOT_PASSWORD: root_password\n    volumes:\n      - db_data:\/var\/lib\/mysql\nvolumes:\n  db_data:\n<\/code><\/pre>\n<\/li>\n<\/ul>\n<\/li>\n
                              • Check database container status<\/strong>:
                                docker-compose ps\n<\/code><\/pre>\nEnsure your database service (db<\/code> or mysql<\/code>) is Up<\/code>.<\/li>\n
                              • Test connectivity from inside the Laravel container<\/strong>:
                                docker exec -it <your_laravel_app_container_name> bash\nphp artisan tinker\n<\/code><\/pre>\nInside tinker, try to connect:
                                DB::connection()->getPdo();\n<\/code><\/pre>\nIf successful, it should return a PDO object. If it throws an error, it indicates a connectivity issue from within the container.<\/li>\n
                              • Rebuild and restart<\/strong>: Sometimes, container network issues can persist. A full rebuild and restart can help:
                                docker-compose down --volumes\ndocker-compose up --build -d\n<\/code><\/pre>\nThen, attempt php artisan migrate<\/code> from within<\/em> the Laravel container:
                                docker exec -it <your_laravel_app_container_name> php artisan migrate\n<\/code><\/pre>\n<\/li>\n<\/ol>\n
                                8. Verify Laravel Application Path<\/h4>\n
                                Ensure you are executing php artisan migrate<\/code> from the root directory of your Laravel project, where the artisan<\/code> script and .env<\/code> file are located.<\/p>\n
                                  \n
                                1. Check current directory<\/strong>:
                                  pwd\n<\/code><\/pre>\n<\/li>\n
                                2. List files<\/strong>:
                                  ls -F\n<\/code><\/pre>\nYou should see artisan<\/code>, .env<\/code>, app\/<\/code>, bootstrap\/<\/code>, config\/<\/code>, etc. If not, cd<\/code> into the correct directory.<\/li>\n<\/ol>\n
                                  After performing these steps, re-run php artisan migrate<\/code>. If the issue persists, carefully review your terminal output for any new error messages that might point to a different problem.<\/p>\n","protected":false},"excerpt":{"rendered":"
                                  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.<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[63],"tags":[147,71,146,152,65,151,6,18],"class_list":["post-56","post","type-post","status-publish","format-standard","hentry","category-runtimes","tag-artisan","tag-database","tag-laravel","tag-migrate","tag-php","tag-sqlstate","tag-troubleshooting","tag-ubuntu-20-04"],"_links":{"self":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/56","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/comments?post=56"}],"version-history":[{"count":2,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/56\/revisions"}],"predecessor-version":[{"id":303,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/56\/revisions\/303"}],"wp:attachment":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/media?parent=56"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/categories?post=56"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/tags?post=56"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}