Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Laravel says the table does not exist (SQLSTATE 42S02, error 1146)

ErrorSQLSTATE[42S02]: Base table or view not found: 1146 Table 'app.posts' doesn't exist

Short answer

MySQL is telling you that the database Laravel connected to has no table with that exact name. Compare three things: the migrations that actually ran, the table name Eloquent derives from the model, and the database and connection in use. On Linux, upper and lower case in the name also matter.

  • Applies to Laravel 12, MySQL 8.4, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Laravel which database it is really using and which migrations ran there. The table name in the error message is the exact name MySQL looked for.

    php artisan migrate:status
    php artisan tinker
    >>> DB::connection()->getDatabaseName()
  2. 2Match what you see, then jump to its fix

    1. 1migrate:status shows the migration as Pending, or it is not listedThe migration for that table has not run on this databaseFix
    2. 2The name in the error is a plural of the model name, but your table has another nameEloquent guessed a different table name than the one you createdFix
    3. 3The table exists when you look in your SQL client, but the database name from the first step differsThe app is connected to a different database or connection than you thinkFix
    4. 4Works on Windows or macOS, fails on a Linux server, and the name in the error has capital lettersTable name case differs on a case-sensitive serverFix

What does the error look like?

  • SQLSTATE[42S02]: Base table or view not found: 1146 Table 'app.posts' doesn't exist

Cause 1 of 4

The migration for that table has not run on this database

1Check

migrate:status lists which migrations have run and which are pending. A new server, a fresh test database or a skipped deploy step leaves tables out.

php artisan migrate:status

2Fix

Run the pending migrations. In production the command asks for confirmation unless you pass --force.

php artisan migrate
# production, non-interactive
php artisan migrate --force

3Verify

The status list shows every migration as Ran.

php artisan migrate:status

Confirmed by laravel.com

Did this fix it?

Cause 2 of 4

Eloquent guessed a different table name than the one you created

1Check

By convention the table name is the snake case plural of the class, so Flight uses flights and AirTrafficController uses air_traffic_controllers. Compare that with your migration.

grep -rn "Schema::create" database/migrations | head
grep -rn "\$table" app/Models

2Fix

Rename the table in a new migration, or tell the model its real table name.

class Flight extends Model
{
    protected $table = 'my_flights';
}

3Verify

Run a query through the model.

php artisan tinker
>>> App\Models\Flight::count()

Confirmed by laravel.com

Did this fix it?

Cause 3 of 4

The app is connected to a different database or connection than you think

1Check

Models use the default connection unless they set a $connection property. The first step printed the database that connection points to; compare it with the one you inspected.

grep -E "^DB_" .env
grep -rn "\$connection" app/Models

2Fix

Fix DB_DATABASE (or the model's connection). If the configuration was cached, rebuild it, because a cached configuration no longer reads .env.

php artisan config:clear
php artisan config:cache

3Verify

The first-step command now prints the database you expect.

php artisan tinker
>>> DB::connection()->getDatabaseName()

Confirmed by laravel.com

Did this fix it?

Cause 4 of 4

Table name case differs on a case-sensitive server

1Check

Table names are case-sensitive on most Unix systems and not on Windows. The lower_case_table_names setting decides how MySQL stores and compares them, and it defaults to 0 on Unix.

mysql -e "SHOW VARIABLES LIKE 'lower_case_table_names'; SHOW TABLES;"

2Fix

Use lowercase names everywhere, in migrations, $table properties and raw SQL. Changing lower_case_table_names is only possible when the server is initialized, so renaming the tables is the practical fix.

RENAME TABLE `Posts` TO `posts`;

3Verify

SHOW TABLES lists the lowercase name and the page loads.

mysql -e "SHOW TABLES;"

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Run php artisan migrate --force as a step of every deploy, after the code is in place.
  • Name tables in lowercase snake case, and let Eloquent derive the model's table name.
  • Print the database name in a health check after deploys so a wrong .env shows up at once.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Eloquent find() fails with Unknown column 'id' in where clause

SQLSTATE[42S22]: Column not found: 1054 Unknown column 'id' in 'where clause' (SQL: select * from `songs` where `id` = 5 limit 1)

Eloquent assumes the primary key is a column called id in the table named after the model.

3 causes, each with a fix

Back end

php artisan migrate stops with could not find driver

could not find driver (Connection: mysql, SQL: select * from information_schema.tables ...)

Laravel talks to the database through a PDO driver, and this error means the PHP that runs artisan has none for your DB_CONNECTION.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.