Maaz Zindani

Loading the index…

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

Eager loading fails with Call to a member function addEagerConstraints() on null

ErrorCall to a member function addEagerConstraints() on null

Short 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.

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

Fix it fast

  1. 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()
  2. 2Match what you see, then jump to its fix

    1. 1Tinker 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. 2Tinker 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. 3Every query on that model fails, even Book::all() with no with() call anywhereThe bad name comes from the model's $with propertyFix

What does the error look like?

  • Call to a member function addEagerConstraints() on null
  • Call 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.php

2Fix

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

Did this fix it?

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

Did this fix it?

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/Models

2Fix

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

Did this fix it?

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

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.