mongodb/laravel-mongodb · error · LogicException

Parent model must be a document model.

Error message

Parent model must be a document model.

What it means

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.

Solutions

  1. Make the parent model extend MongoDB\Laravel\Eloquent\Model (and use the MongoDB connection)
  2. Use a standard hasOne/hasMany relation if the parent is a SQL/Eloquent model
  3. Verify the class hierarchy of the model returned by the relation's parent()

Example fix

// before
class Author extends \Illuminate\Database\Eloquent\Model {
  public function addresses() { return $this->embedsMany(Address::class); }
}
// after
class Author extends \MongoDB\Laravel\Eloquent\Model {
  public function addresses() { return $this->embedsMany(Address::class); }
}
Defensive patterns

Strategy: validation

Validate before calling

if (!is_a(static::class, \MongoDB\Laravel\Eloquent\Model::class, true)) {
    throw new \LogicException('embeds* relations require the parent to extend MongoDB\\Laravel\\Eloquent\\Model.');
}

Type guard

function parentIsDocumentModel(\Illuminate\Database\Eloquent\Model $m): bool {
    return $m instanceof \MongoDB\Laravel\Eloquent\Model;
}

Try / catch

try {
    $addresses = $author->addresses;
} catch (\LogicException $e) {
    if (str_contains($e->getMessage(), 'Parent model must be a document model')) {
        throw new \DomainException('Configure the relation on a MongoDB document model.');
    }
    throw $e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/7e806288251de49a. Report an issue: GitHub.

Appendix: source

Thrown at src/Relations/EmbedsOneOrMany.php:60

     *
     * @var string
     */
    protected $foreignKey;

    /**
     * The "name" of the relationship.
     *
     * @var string
     */
    protected $relation;

    /**
     * Create a new embeds many relationship instance.
     */
    public function __construct(Builder $query, Model $parent, Model $related, string $localKey, string $foreignKey, string $relation)
    {
        if (! DocumentModel::isDocumentModel($parent)) {
            throw new LogicException('Parent model must be a document model.');
        }

        if (! DocumentModel::isDocumentModel($related)) {
            throw new LogicException('Related model must be a document model.');
        }

        parent::__construct($query, $parent);

        $this->related    = $related;
        $this->localKey   = $localKey;
        $this->foreignKey = $foreignKey;
        $this->relation   = $relation;

        // If this is a nested relation, we need to get the parent query instead.
        $parentRelation = $this->getParentRelation();
        if ($parentRelation) {
            $this->query = $parentRelation->getQuery();
        }

View on GitHub (pinned to 0634653039)