laravel/framework · error · LogicException

:: must return a relationship instance, but "null" was…

Error message

%s::%s must return a relationship instance, but "null" was returned. Was the "return" keyword used?

What it means

Thrown by getRelationshipFromMethod() when a relation-defining method returns null. Eloquent calls the method and checks the result is a Relation instance; null specifically indicates the developer forgot the `return` keyword inside the method body. The message points at the exact class and method so the missing return is obvious.

Solutions

1. Add the missing `return` keyword before the relation builder call.
2. Make sure every branch of the method returns a Relation instance.
3. If the method is intentionally not a relation, rename it so Eloquent does not treat it as one.

Example fix

// before
public function posts()
{
    $this->hasMany(Post::class); // missing return
}

// after
public function posts()
{
    return $this->hasMany(Post::class);
}

$relation = (new \ReflectionMethod($model, $method))->invoke($model);
if (! $relation instanceof \Illuminate\Database\Eloquent\Relations\Relation) {
    throw new \LogicException(static::class . "::{$method} does not return a Relation");
}

function isRelationReturning(string $class, string $method): bool
{
    if (! method_exists($class, $method)) {
        return false;
    }
    $instance = new $class;
    $result = (new \ReflectionMethod($class, $method))->invoke($instance);
    return $result instanceof \Illuminate\Database\Eloquent\Relations\Relation;
}

When it happens

Trigger: Defining a relation method whose body calls $this->hasMany(...) but omits return, e.g. `public function posts() { $this->hasMany(Post::class); }`. Accessing the relation triggers getRelationshipFromMethod(), which sees null and throws.

Common situations: Copy-paste error when scaffolding relations; refactoring a relation method and deleting the return by accident; a relation method that conditionally returns and has a branch missing a return statement.

Related errors

• :: must return a relationship instance.
• No morph map defined for model
• Add fillable property
• Add [ ] to fillable property to allow mass assignment on […
• Call to undefined cast

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/fe1ac43dbd44f93c. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Database/Eloquent/Concerns/HasAttributes.php:641

        throw new LazyLoadingViolationException($this, $key);
    }

    /**
     * Get a relationship value from a method.
     *
     * @param  string  $method
     * @return mixed
     *
     * @throws \LogicException
     */
    protected function getRelationshipFromMethod($method)
    {
        $relation = Relation::withConstraintsForNestedRelation(fn () => $this->$method());

        if (! $relation instanceof Relation) {
            if (is_null($relation)) {
                throw new LogicException(sprintf(
                    '%s::%s must return a relationship instance, but "null" was returned. Was the "return" keyword used?', static::class, $method
                ));
            }

            throw new LogicException(sprintf(
                '%s::%s must return a relationship instance.', static::class, $method
            ));
        }

        return tap($relation->getResults(), function ($results) use ($method) {
            $this->setRelation($method, $results);
        });
    }

    /**
     * Determine if a get mutator exists for an attribute.
     *
     * @param  string  $key

View on GitHub (pinned to e0f6eb3518)