Maaz Zindani

Loading the index…

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

A Laravel migration fails because Doctrine DBAL is missing

Errorphp artisan migrate stops with a class not found error that names a Doctrine\DBAL class

Short answer

Before Laravel 11, changing, renaming or dropping some columns needed the doctrine/dbal package. If a migration with change() fails on a missing Doctrine class, run composer require doctrine/dbal on Laravel 10 or older. Laravel 11 and newer no longer depend on it, so leftover DBAL code is the thing to remove.

  • Applies to Laravel 10, Laravel 12, PHP 8.3, Composer 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the Laravel version first. The fix is different on either side of version 11.

    php artisan --version
    composer show doctrine/dbal
  2. 2Match what you see, then jump to its fix

    1. 1The failing migration calls ->change() or renameColumn(), and Laravel is below 11Laravel 10 or older needs doctrine/dbal to modify columnsFix
    2. 2Laravel is 11 or newer, and the stack trace points to your own code, a config entry or an old package that touches DBALLaravel 11 or newer: code still expects Doctrine DBALFix

What does the error look like?

  • php artisan migrate stops with a class not found error that names a Doctrine\DBAL class
  • The failing migration calls change() or renameColumn()

Cause 1 of 2

Laravel 10 or older needs doctrine/dbal to modify columns

1Check

The Laravel 10 migrations docs say doctrine/dbal must be installed before modifying a column on SQLite, and before renaming a column on older databases (MySQL below 8.0.3, MariaDB below 10.5.2, SQLite below 3.25.0).

php artisan --version
grep -rn "change()\|renameColumn" database/migrations | tail -n 5

2Fix

Install the package with Composer and run the migration again.

composer require doctrine/dbal
php artisan migrate

3Verify

The migration runs and the column has its new definition.

php artisan migrate:status

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 2

Laravel 11 or newer: code still expects Doctrine DBAL

1Check

The Laravel 11 upgrade guide says the framework no longer depends on Doctrine DBAL, and lists removed methods such as getDoctrineConnection() and registerDoctrineType().

grep -rn "Doctrine\|getDoctrineConnection\|registerDoctrineType" app/ database/ config/

2Fix

Delete the dbal.types registration from the database config and replace table inspection with Laravel's own Schema methods. The guide says the doctrine/dbal dependency can be removed if you added it.

use Illuminate\Support\Facades\Schema;

Schema::getColumns('users');
Schema::getIndexes('users');
Schema::getForeignKeys('users');
// then: composer remove doctrine/dbal

3Verify

Run the migrations from a clean database.

php artisan migrate:fresh

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Note the Laravel version in the project README, so people pick the right fix.
  • Run migrations in CI against a fresh database on every pull request.
  • When upgrading to Laravel 11 or newer, follow the upgrade guide's DBAL section and remove the leftover code.

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

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

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.