{"id":55,"date":"2026-07-13T00:00:00","date_gmt":"2026-07-13T00:00:00","guid":{"rendered":"http:\/\/\/var\/www\/html\/?p=55"},"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-macos-local-environment","status":"publish","type":"post","link":"https:\/\/butitworkedlocal.com\/laravel-artisan-migrate-sqlstate-base-table-or-view-not-found-on-macos-local-environment\/","title":{"rendered":"Troubleshooting: Laravel `artisan migrate` SQLSTATE Base Table or View Not Found on macOS Local Environment"},"content":{"rendered":"\n

Resolve the 'SQLSTATE base table or view not found' error during Laravel migrations on macOS. This guide covers common causes and fixes for local development setups.<\/strong><\/p>\n\n\n

Introduction<\/h2>\n

Encountering a SQLSTATE base table or view not found<\/code> error while running php artisan migrate<\/code> in your Laravel project on a macOS local development environment can be frustrating. This error typically indicates that your Laravel application is unable to locate or interact with expected database tables, such as the migrations<\/code> table or other application-specific tables, despite seemingly connecting to the database. This guide will walk you through the common causes and provide a systematic approach to resolve this issue, ensuring your development workflow remains smooth.<\/p>\n

Symptom & Error Signature<\/h3>\n

When you execute php artisan migrate<\/code> in your terminal, you might see output similar to this:<\/p>\n

php artisan migrate\n<\/code><\/pre>\n
   INFO  Running migrations.\n\n  2023_01_01_000000_create_users_table ..................................................................................... RUNNING\n  2023_01_01_000000_create_users_table ..................................................................................... FAILED\n\n   IlluminateDatabaseQueryException\n\n  SQLSTATE[42S02]: Base table or view not found: 1146 Table 'your_database_name.users' doesn't exist (SQL: create table `users` (`id` bigint unsigned not null auto_increment primary key, `name` varchar(255) not null, `email` varchar(255) not null, `email_verified_at` timestamp null, `password` varchar(255) not null, `remember_token` varchar(100) null, `created_at` timestamp null, `updated_at` timestamp null) default character set utf8mb4 collate utf8mb4_unicode_ci)\n\n  at vendor\/laravel\/framework\/src\/Illuminate\/Database\/Connection.php:826\n    822|         \/\/ If an exception occurs while attempting to run a query, we'll format the error\n    823|         \/\/ message to include the bindings with the query, which will make it much\n    824|         \/\/ easier to debug whilst still getting the actual exception instance.\n    825|         catch (Exception $e) {\n  > 826|             throw new QueryException(\n    827|                 $query, $this->prepareBindings($bindings), $e\n    828|             );\n    829|         }\n    830|\n<\/code><\/pre>\n
The key part of the error message is SQLSTATE[42S02]: Base table or view not found<\/code>. This usually occurs when Laravel attempts to create the migrations<\/code> table (to track executed migrations) or your first application table (like users<\/code>) and cannot find it or the database itself isn't correctly set up or targeted.<\/p>\n
Root Cause Analysis<\/h3>\n
This error, specifically SQLSTATE[42S02]: Base table or view not found<\/code>, primarily indicates that while your Laravel application successfully connected<\/em> to a database server, it could not find a specific database or table it was trying to access or create. The most common underlying reasons for this on a macOS local environment include:<\/p>\n
    \n
  1. Incorrect Database Configuration:<\/strong> The .env<\/code> file contains incorrect database credentials, host, port, or database name, leading Laravel to connect to the wrong database server, a non-existent database, or a database where the specified table truly doesn't exist.<\/li>\n
  2. Database Service Not Running:<\/strong> The MySQL or PostgreSQL database server (or its Docker container) is not currently running on your macOS machine. Laravel might fail to establish a connection, or worse, connect to a different<\/em> local database instance that is running (e.g., a default system-level database or another project's database).<\/li>\n
  3. Database Not Created:<\/strong> The database specified in your .env<\/code> file (e.g., DB_DATABASE=your_app_db<\/code>) has not been manually created on your database server. Laravel's migration command doesn't create the database itself; it only creates tables within an existing<\/em> database.<\/li>\n
  4. Stale Configuration Cache:<\/strong> Laravel's configuration might be cached, causing it to use outdated database credentials even after you've updated your .env<\/code> file.<\/li>\n
  5. Insufficient Database User Privileges:<\/strong> The database user specified in .env<\/code> (e.g., DB_USERNAME=root<\/code>) lacks the necessary permissions to create tables or access the specified database.<\/li>\n
  6. Conflicting Database Services:<\/strong> Multiple database services (e.g., Homebrew MySQL and a Dockerized MySQL instance) might be running simultaneously, leading to confusion about which database server Laravel is connecting to.<\/li>\n
  7. Docker\/Laravel Sail Specific Issues:<\/strong> If using Docker, the database container might not be healthy, or its internal hostname\/port mapping might be misconfigured.<\/li>\n<\/ol>\n
    Step-by-Step Resolution<\/h3>\n
    Follow these steps to diagnose and resolve the SQLSTATE base table or view not found<\/code> error.<\/p>\n
    1. Verify Database Service Status<\/h4>\n
    Ensure your database server (MySQL, PostgreSQL, or Docker container) is actively running.<\/p>\n
    For Homebrew-installed MySQL\/PostgreSQL:<\/strong><\/p>\n
    # To check MySQL status\nbrew services list | grep mysql\n# Expected output: mysql started your_user_name \/path\/to\/mysql.plist\n\n# To check PostgreSQL status\nbrew services list | grep postgresql\n# Expected output: postgresql started your_user_name \/path\/to\/postgresql.plist\n<\/code><\/pre>\n
    If the service is not started<\/code>, start it:<\/p>\n
    brew services start mysql\n# OR\nbrew services start postgresql\n<\/code><\/pre>\n
    For Docker\/Laravel Sail:<\/strong><\/p>\n
    # Navigate to your Laravel project root\ncd \/path\/to\/your\/laravel\/project\n\n# Check running Docker containers\ndocker ps -a\n# OR if using docker compose directly\ndocker compose ps -a\n<\/code><\/pre>\n
    Look for containers named similar to your_project_name-mysql-1<\/code> or your_project_name-pgsql-1<\/code>. Ensure their STATUS<\/code> is Up<\/code>. If they are stopped or exited:<\/p>\n
    # For Laravel Sail\nsail up -d\n\n# For generic Docker Compose\ndocker compose up -d\n<\/code><\/pre>\n
    Always ensure your database service is running before attempting any database operations with Laravel.<\/p>\n<\/blockquote>\n
    2. Inspect .env<\/code> Configuration<\/h4>\n
    The .env<\/code> file is crucial for local development. Double-check every database-related entry.<\/p>\n
    # Open your .env file in a text editor\nnano .env\n<\/code><\/pre>\n
    Review the DB_CONNECTION<\/code>, DB_HOST<\/code>, DB_PORT<\/code>, DB_DATABASE<\/code>, DB_USERNAME<\/code>, and DB_PASSWORD<\/code> variables.<\/p>\n
    Example for MySQL:<\/strong><\/p>\n
    DB_CONNECTION=mysql\nDB_HOST=127.0.0.1      # Or localhost. If using Docker, it might be the service name (e.g., mysql or db)\nDB_PORT=3306           # Standard MySQL port\nDB_DATABASE=your_app_db_name # IMPORTANT: This must be an existing database\nDB_USERNAME=root       # Or your database user\nDB_PASSWORD=            # Or your database user's password\n<\/code><\/pre>\n
    Example for PostgreSQL:<\/strong><\/p>\n
    DB_CONNECTION=pgsql\nDB_HOST=127.0.0.1      # Or localhost. If using Docker, it might be the service name (e.g., pgsql or db)\nDB_PORT=5432           # Standard PostgreSQL port\nDB_DATABASE=your_app_db_name # IMPORTANT: This must be an existing database\nDB_USERNAME=postgres   # Or your database user\nDB_PASSWORD=secret      # Or your database user's password\n<\/code><\/pre>\n
    Pay close attention to DB_HOST<\/code>. For Docker\/Laravel Sail, DB_HOST<\/code> should typically be the service name defined in docker-compose.yml<\/code> (e.g., mysql<\/code> or db<\/code>), not<\/em> 127.0.0.1<\/code> unless port mapping is explicitly used for external access. For Valet\/Herd, 127.0.0.1<\/code> or localhost<\/code> is usually correct.<\/p>\n<\/blockquote>\n
    3. Confirm Database Existence and Accessibility<\/h4>\n
    Laravel's artisan migrate<\/code> command expects the database specified in DB_DATABASE<\/code> to already exist. It does not create the database itself.<\/p>\n
    Connect via mysql<\/code> client (for MySQL):<\/strong><\/p>\n
    mysql -u DB_USERNAME -p -h DB_HOST -P DB_PORT\n# Example: mysql -u root -p -h 127.0.0.1 -P 3306\n# Enter password when prompted.\n<\/code><\/pre>\n
    Once connected, list existing databases:<\/p>\n
    SHOW DATABASES;\n<\/code><\/pre>\n
    If your DB_DATABASE<\/code> is not listed, create it:<\/p>\n
    CREATE DATABASE your_app_db_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n<\/code><\/pre>\n
    Then exit the client:<\/p>\n
    EXIT;\n<\/code><\/pre>\n
    Connect via psql<\/code> client (for PostgreSQL):<\/strong><\/p>\n
    psql -U DB_USERNAME -h DB_HOST -p DB_PORT\n# Example: psql -U postgres -h 127.0.0.1 -p 5432\n# Enter password when prompted.\n<\/code><\/pre>\n
    Once connected, list existing databases:<\/p>\n
    l\n<\/code><\/pre>\n
    If your DB_DATABASE<\/code> is not listed, create it:<\/p>\n
    CREATE DATABASE your_app_db_name;\n<\/code><\/pre>\n
    Then exit the client:<\/p>\n
    q\n<\/code><\/pre>\n
    4. Clear Laravel Configuration Caches<\/h4>\n
    Stale cached configuration can prevent Laravel from reading your updated .env<\/code> file correctly. Always clear caches after making changes to .env<\/code> or configuration files.<\/p>\n
    php artisan cache:clear\nphp artisan config:clear\nphp artisan route:clear\nphp artisan view:clear\ncomposer dump-autoload\n<\/code><\/pre>\n
    Running php artisan config:clear<\/code> is particularly important after modifying the .env<\/code> file, as Laravel's configuration cache can override .env<\/code> variables.<\/p>\n<\/blockquote>\n
    5. Verify Database User Privileges<\/h4>\n
    Ensure the database user (e.g., root<\/code>, postgres<\/code>, or a custom user) specified in your .env<\/code> has sufficient privileges to create, alter, and drop tables on the database.<\/p>\n
    For MySQL (connected as a privileged user like root<\/code>):<\/strong><\/p>\n
    -- Grant all privileges to 'your_username' on 'your_app_db_name'\nGRANT ALL PRIVILEGES ON your_app_db_name.* TO 'your_username'@'localhost' IDENTIFIED BY 'your_password';\nFLUSH PRIVILEGES;\n<\/code><\/pre>\n
    Replace your_username<\/code>, your_password<\/code>, your_app_db_name<\/code>, and localhost<\/code> with your specific values. If DB_HOST<\/code> in .env<\/code> is 127.0.0.1<\/code>, use 'your_username'@'127.0.0.1'<\/code>. If using Docker, it might be 'your_username'@'%'<\/code> for any host, but be cautious with root<\/code> for security.<\/p>\n
    For PostgreSQL (connected as a privileged user like postgres<\/code>):<\/strong><\/p>\n
    -- Grant all privileges on database 'your_app_db_name' to 'your_username'\nGRANT ALL PRIVILEGES ON DATABASE your_app_db_name TO your_username;\n<\/code><\/pre>\n
    6. Re-run Migrations<\/h4>\n
    After performing the above checks and corrections, attempt to run your migrations again.<\/p>\n
    php artisan migrate\n<\/code><\/pre>\n
    If you previously ran some migrations on a different or corrupted database, and you are starting fresh, you might consider:<\/p>\n
    > [!WARNING]\n> `php artisan migrate:fresh` will drop *all tables* from your database before running migrations. Only use this if you are confident you don't need existing data, especially in a local development environment.\n\nphp artisan migrate:fresh --seed # Drops all tables, runs migrations, and then runs seeders\n<\/code><\/pre>\n
    7. Specific Environment Considerations (Docker\/Laravel Sail, Valet\/Herd)<\/h4>\n
    For Laravel Sail (Docker):<\/strong><\/p>\n
      \n
    • If you're using Sail, DB_HOST<\/code> in your .env<\/code> should usually be mysql<\/code> (for MySQL) or pgsql<\/code> (for PostgreSQL), as defined in your docker-compose.yml<\/code>.<\/li>\n
    • Ensure the Sail containers are healthy: sail ps<\/code>. If issues persist, try rebuilding and restarting:
      sail down --rmi all -v # Removes containers, images, and volumes (data loss for DB)\nsail up -d\nsail artisan migrate # Use sail artisan instead of php artisan\n<\/code><\/pre>\n<\/li>\n<\/ul>\n
      For Laravel Valet\/Herd:<\/strong><\/p>\n
        \n
      • Valet and Herd manage services (PHP, Nginx, MySQL\/PostgreSQL) via Homebrew. Ensure they are running as described in step 1.<\/li>\n
      • Sometimes, a simple restart helps:
        valet restart\n# OR\nherd restart\n<\/code><\/pre>\n<\/li>\n<\/ul>\n
        8. Check for Other Processes on Database Port<\/h4>\n
        Ensure no other applications are using the default database port (e.g., 3306 for MySQL, 5432 for PostgreSQL). This can lead to connection issues.<\/p>\n
        # For MySQL (port 3306)\nsudo lsof -i :3306\n\n# For PostgreSQL (port 5432)\nsudo lsof -i :5432\n<\/code><\/pre>\n
        If another process is listening, identify it and stop it, or configure your database (and Laravel) to use a different port.<\/p>\n
        By systematically working through these steps, you should be able to identify and resolve the SQLSTATE base table or view not found<\/code> error, allowing your Laravel migrations to run successfully on your macOS local development environment.<\/p>\n","protected":false},"excerpt":{"rendered":"
        Resolve the ‘SQLSTATE base table or view not found’ error during Laravel migrations on macOS. This guide covers common causes and fixes for local development setups.<\/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,40,146,47,148,149,65,150,151],"class_list":["post-55","post","type-post","status-publish","format-standard","hentry","category-runtimes","tag-artisan","tag-devops","tag-laravel","tag-macos","tag-migration","tag-mysql","tag-php","tag-postgresql","tag-sqlstate"],"_links":{"self":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/55","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=55"}],"version-history":[{"count":2,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/55\/revisions"}],"predecessor-version":[{"id":302,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/55\/revisions\/302"}],"wp:attachment":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/media?parent=55"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/categories?post=55"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/tags?post=55"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}