Eager loading fails with Call to a member function addEagerConstraints() on null
Call to a member function addEagerConstraints() on nullShort answer
To eager load, Eloquent calls the named method on an empty model and expects a relationship object back. This error means the method returned null. The usual reasons: the method has no return statement, the name given to with() is a helper and not a relationship, or the name comes from a model's $with property.
Fix it fast
1Find out which cause you have
Call the relationship method on an empty model, which is what Eloquent does while it eager loads. A relation object means this method is fine. null means the method is the cause.
php artisan tinker >>> (new App\Models\User)->posts()2Match what you see, then jump to its fix
- 1
Tinker prints null, and the method body calls $this->hasMany(...) or a similar method without return in front of itThe relationship method has no return statementFix - 2
Tinker prints null for that name, and the method is a helper that returns nothing or a lookup that found no rowThe name given to with() or load() is a helper, not a relationshipFix - 3
Every query on that model fails, even Book::all() with no with() call anywhereThe bad name comes from the model's $with propertyFix
- 1
What does the error look like?
Call to a member function addEagerConstraints() on nullCall to a member function addEagerConstraints() on null in vendor/laravel/framework/src/Illuminate/Database/Eloquent/Builder.php
Cause 1 of 3
The relationship method has no return statement
1Check
Eloquent reads the object a relationship method returns. A method that builds the relation and then ends, or that returns only inside an if, hands back null. For a dotted name such as posts.comments, test the method on each model along the path.
grep -n -A4 "function posts" app/Models/User.php2Fix
Return the relation from every path of the method, and declare the return type as the documentation examples do.
use Illuminate\Database\Eloquent\Relations\HasMany;
public function posts(): HasMany
{
return $this->hasMany(Post::class);
}3Verify
Tinker now prints a relation object, and the eager load runs.
>>> (new App\Models\User)->posts()
>>> App\Models\User::with('posts')->first()Confirmed by laravel.com
Cause 2 of 3
The name given to with() or load() is a helper, not a relationship
1Check
Eloquent accepts only a method that returns a relationship object. A helper with no return statement, or one that ends in a lookup such as first() that comes back empty, gives null, which is the value the error names.
>>> (new App\Models\User)->latestPost()2Fix
Declare a real relationship for the data you want. For the most recent related row, the documentation uses hasOne together with latestOfMany. Keep the helper out of with().
use Illuminate\Database\Eloquent\Relations\HasOne;
public function latestOrder(): HasOne
{
return $this->hasOne(Order::class)->latestOfMany();
}3Verify
The eager load names the new relationship.
App\Models\User::with('latestOrder')->get();Confirmed by laravel.com
Cause 3 of 3
The bad name comes from the model's $with property
1Check
Relationships listed in $with are eager loaded on every query for the model. One wrong entry there makes each query hit this error.
grep -rn 'protected $with' app/Models2Fix
Open each method named in the property and fix it as in the first two causes. To skip a relationship for a single query while you repair it, use without().
$books = Book::without('author')->get();3Verify
The plain query runs, and with the repaired method the default eager load works again.
App\Models\Book::first();Confirmed by laravel.com
How do I stop it coming back?
- Declare a return type (HasMany, BelongsTo and so on) on every relationship method, so PHP rejects a method that returns nothing.
- Keep relationship methods free of logic: build the relation and return it, and put filtering in scopes.
- Write helpers that run queries under their own names, and never pass them to with().
- Add one test per model that calls each relationship method and asserts it returns a Relation.
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
RelationNotFoundException: with(), load() or $with names a relation the model does not have
Call to undefined relationship [author] on model [App\Models\Comment] of type [App\Models\Video].
Eloquent looked for a method named after the relationship on the model in the message and found none.
3 causes, each with a fixBack end
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack 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 fixBack end
composer install says the lock file is not compatible and asks for update
Your lock file does not contain a compatible set of packages. Please run composer update.
composer install checked the locked packages against this machine's PHP and extensions and found a conflict.
3 causes, each with a fixBack 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 fixBack end
composer require laravel/passport stops with 'requirements could not be resolved'
... but these were not loaded, likely because it conflicts with another require.
Composer found no Passport release that fits your project at once.
4 causes, each with a fix