Maaz Zindani

Loading the index…

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

RelationNotFoundException: with(), load() or $with names a relation the model does not have

ErrorIlluminate\Database\Eloquent\RelationNotFoundException: Call to undefined relationship [comments] on model [App\Models\Post].

Short answer

Eloquent looked for a method named after the relationship on the model in the message and found none. Read the class in the second bracket: it tells you which model lacks the method. Add or rename the method, fix a dotted path that names a relation on the wrong model, or remove a stale entry from the 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

    Take the class from the second bracket of the message and list what that model really defines. model:show prints its attributes and relations. If the relation is not in the list, one of the causes below applies.

    php artisan model:show Post
  2. 2Match what you see, then jump to its fix

    1. 1The model in the message is the one you expected, and the name in the first bracket is a typo or the wrong pluralThe relationship method is missing or named differently on that modelFix
    2. 2The model in the message is the related model, for example Comment, not the one you queriedA dotted path names a relation that belongs to the second modelFix
    3. 3The error appears on every query of that model, even Post::find(1), and no with() call shows up in the traceThe model's $with property still lists a relation that no longer existsFix

What does the error look like?

  • Illuminate\Database\Eloquent\RelationNotFoundException: Call to undefined relationship [comments] on model [App\Models\Post].
  • Call to undefined relationship [author] on model [App\Models\Comment] of type [App\Models\Video].

Cause 1 of 3

The relationship method is missing or named differently on that model

1Check

Eloquent turns a name passed to with(), load() or loadMissing() into a call of the method with that name on the model. If the method is not there, the call fails and the exception is raised. A relation defined as comment() does not answer to comments.

grep -n "function " app/Models/Post.php

2Fix

Define the method, or use the name it really has. The method name is the relationship name, and it has to return the relation.

// app/Models/Post.php
public function comments()
{
    return $this->hasMany(Comment::class);
}

// the name passed to with() matches the method
$posts = Post::with('comments')->get();

3Verify

model:show lists the relation, and the query runs.

php artisan model:show Post
# in php artisan tinker
>>> App\Models\Post::with('comments')->first()->comments->count();

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

A dotted path names a relation that belongs to the second model

1Check

A path such as comments.author loads comments on Post and then author on Comment. The second name is resolved against the related model, so a missing author() on Comment raises the error with Comment in the brackets.

grep -rnE "(with|load|loadMissing)\('[A-Za-z_]+\.[A-Za-z_.]+'" app/

2Fix

Add the method to the related model, or correct the path so that every segment is a relation of the model before it.

// app/Models/Comment.php
public function author()
{
    return $this->belongsTo(User::class, 'user_id');
}

$posts = Post::with('comments.author')->get();

3Verify

The nested relation loads.

# in php artisan tinker
>>> App\Models\Post::with('comments.author')->first()->comments->first()?->author;

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The model's $with property still lists a relation that no longer exists

1Check

Relationships named in the $with property are loaded on every query of the model. After a method was renamed or deleted, the old name in $with fails each time.

grep -rn "\$with" app/Models/

2Fix

Remove the stale name from $with or rename it to the current method. For one query you can skip the default list with without(), or replace it with withOnly().

// app/Models/Post.php
protected $with = ['author'];   // author() must exist on Post

// one query without the default relations
$posts = Post::without('author')->get();

3Verify

A plain query on the model runs again.

# in php artisan tinker
>>> App\Models\Post::first();

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Keep relationship names in one place per model and refer to them by the same string everywhere. When one is renamed, search for the old string in with(), load(), loadMissing() and $with.
  • Cover the eager loads of each main page with a feature test, so a renamed relation fails in the test run and not in production.
  • Read the model in the second bracket of the message before you open any file. It names the class to fix.
  • Run php artisan model:show on a model to see its relations next to its columns.

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.