{"record":{"id":"fe1ac43dbd44f93c","repo":"laravel/framework","slug":"s-s-must-return-a-relationship-instance-but-n","errorCode":null,"errorMessage":"%s::%s must return a relationship instance, but \"null\" was returned. Was the \"return\" keyword used?","messagePattern":"(.+?)::(.+?) must return a relationship instance, but \"null\" was returned\\. Was the \"return\" keyword used\\?","errorType":"exception","errorClass":"LogicException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Eloquent/Concerns/HasAttributes.php","lineNumber":641,"sourceCode":"\n        throw new LazyLoadingViolationException($this, $key);\n    }\n\n    /**\n     * Get a relationship value from a method.\n     *\n     * @param  string  $method\n     * @return mixed\n     *\n     * @throws \\LogicException\n     */\n    protected function getRelationshipFromMethod($method)\n    {\n        $relation = Relation::withConstraintsForNestedRelation(fn () => $this->$method());\n\n        if (! $relation instanceof Relation) {\n            if (is_null($relation)) {\n                throw new LogicException(sprintf(\n                    '%s::%s must return a relationship instance, but \"null\" was returned. Was the \"return\" keyword used?', static::class, $method\n                ));\n            }\n\n            throw new LogicException(sprintf(\n                '%s::%s must return a relationship instance.', static::class, $method\n            ));\n        }\n\n        return tap($relation->getResults(), function ($results) use ($method) {\n            $this->setRelation($method, $results);\n        });\n    }\n\n    /**\n     * Determine if a get mutator exists for an attribute.\n     *\n     * @param  string  $key","sourceCodeStart":623,"sourceCodeEnd":659,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Eloquent/Concerns/HasAttributes.php#L623-L659","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the missing `return` keyword before the relation builder call.","Make sure every branch of the method returns a Relation instance.","If the method is intentionally not a relation, rename it so Eloquent does not treat it as one."],"exampleFix":"// before\npublic function posts()\n{\n    $this->hasMany(Post::class); // missing return\n}\n\n// after\npublic function posts()\n{\n    return $this->hasMany(Post::class);\n}","handlingStrategy":"type-guard","validationCode":"$relation = (new \\ReflectionMethod($model, $method))->invoke($model);\nif (! $relation instanceof \\Illuminate\\Database\\Eloquent\\Relations\\Relation) {\n    throw new \\LogicException(static::class . \"::{$method} does not return a Relation\");\n}","typeGuard":"function isRelationReturning(string $class, string $method): bool\n{\n    if (! method_exists($class, $method)) {\n        return false;\n    }\n    $instance = new $class;\n    $result = (new \\ReflectionMethod($class, $method))->invoke($instance);\n    return $result instanceof \\Illuminate\\Database\\Eloquent\\Relations\\Relation;\n}","tryCatchPattern":null,"preventionTips":["Always `return` the relation builder object from relation methods.","Lint relation methods to ensure every branch ends with a return statement.","Add a smoke test that calls each relation method and asserts instanceof Relation."],"tags":["eloquent","relations","return-statement","developer-error"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}