{"record":{"id":"7e806288251de49a","repo":"mongodb/laravel-mongodb","slug":"parent-model-must-be-a-document-model","errorCode":null,"errorMessage":"Parent model must be a document model.","messagePattern":"Parent model must be a document model\\.","errorType":"exception","errorClass":"LogicException","httpStatus":null,"severity":"error","filePath":"src/Relations/EmbedsOneOrMany.php","lineNumber":60,"sourceCode":"     *\n     * @var string\n     */\n    protected $foreignKey;\n\n    /**\n     * The \"name\" of the relationship.\n     *\n     * @var string\n     */\n    protected $relation;\n\n    /**\n     * Create a new embeds many relationship instance.\n     */\n    public function __construct(Builder $query, Model $parent, Model $related, string $localKey, string $foreignKey, string $relation)\n    {\n        if (! DocumentModel::isDocumentModel($parent)) {\n            throw new LogicException('Parent model must be a document model.');\n        }\n\n        if (! DocumentModel::isDocumentModel($related)) {\n            throw new LogicException('Related model must be a document model.');\n        }\n\n        parent::__construct($query, $parent);\n\n        $this->related    = $related;\n        $this->localKey   = $localKey;\n        $this->foreignKey = $foreignKey;\n        $this->relation   = $relation;\n\n        // If this is a nested relation, we need to get the parent query instead.\n        $parentRelation = $this->getParentRelation();\n        if ($parentRelation) {\n            $this->query = $parentRelation->getQuery();\n        }","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/mongodb/laravel-mongodb/blob/0634653039468ceb0268a69192bdac64469ed043/src/Relations/EmbedsOneOrMany.php#L42-L78","documentation":"EmbedsOneOrMany relations only work when the parent is a MongoDB document model (DocumentModel). The constructor checks this up front and throws a LogicException otherwise, because embedding requires MongoDB-specific document storage semantics.","triggerScenarios":"Defining an embedsOne()/embedsMany() relation whose parent model extends Illuminate\\Database\\Eloquent\\Model (or any non-document model), then instantiating the relation by accessing the relation property.","commonSituations":"Using embeds* relations on a model that extends the vanilla Eloquent Model instead of MongoDB\\Laravel\\Eloquent\\Model; refactoring an existing SQL model to embed documents without changing its base class.","solutions":["Make the parent model extend MongoDB\\Laravel\\Eloquent\\Model (and use the MongoDB connection)","Use a standard hasOne/hasMany relation if the parent is a SQL/Eloquent model","Verify the class hierarchy of the model returned by the relation's parent()"],"exampleFix":"// before\nclass Author extends \\Illuminate\\Database\\Eloquent\\Model {\n  public function addresses() { return $this->embedsMany(Address::class); }\n}\n// after\nclass Author extends \\MongoDB\\Laravel\\Eloquent\\Model {\n  public function addresses() { return $this->embedsMany(Address::class); }\n}","handlingStrategy":"validation","validationCode":"if (!is_a(static::class, \\MongoDB\\Laravel\\Eloquent\\Model::class, true)) {\n    throw new \\LogicException('embeds* relations require the parent to extend MongoDB\\\\Laravel\\\\Eloquent\\\\Model.');\n}","typeGuard":"function parentIsDocumentModel(\\Illuminate\\Database\\Eloquent\\Model $m): bool {\n    return $m instanceof \\MongoDB\\Laravel\\Eloquent\\Model;\n}","tryCatchPattern":"try {\n    $addresses = $author->addresses;\n} catch (\\LogicException $e) {\n    if (str_contains($e->getMessage(), 'Parent model must be a document model')) {\n        throw new \\DomainException('Configure the relation on a MongoDB document model.');\n    }\n    throw $e;\n}","preventionTips":["Always extend MongoDB\\Laravel\\Eloquent\\Model for models used in embeds* relations","Keep SQL-backed and document-backed models in separate namespaces","Add an architecture test asserting embeds* hosts are DocumentModel instances"],"tags":["php","mongodb","eloquent","relations"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"0634653039468ceb0268a69192bdac64469ed043","analyzedAt":"2026-09-15T02:56:37.067Z","contentChangedAt":"2026-09-15T02:56:37.067Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}