What causes "Related model must be a document model." in mongodb/laravel-mongodb?

Make the related model extend MongoDB\Laravel\Eloquent\Model

mongodb/laravel-mongodb · error · LogicException

Related model must be a document model.

Error message

Related model must be a document model.

What it means

EmbedsOneOrMany requires the RELATED model to be a MongoDB document model, since embedded documents are stored as BSON sub-documents. The constructor validates this immediately and throws a LogicException if the related class is not a DocumentModel.

Solutions

Make the related model extend MongoDB\Laravel\Eloquent\Model
Replace the embeds* relation with belongsTo/hasMany if the related model lives in a SQL table
Check that the class passed to embedsOne/embedsMany is the intended document model

Example fix

// before
public function tags() { return $this->embedsMany(\App\Models\Tag::class); } // Tag extends Eloquent\Model
// after
public function tags() { return $this->embedsMany(\App\Documents\Tag::class); } // extends MongoDB\Laravel\Eloquent\Model

Defensive patterns

Strategy: validation

Validate before calling

if (!is_a($relatedClass, \MongoDB\Laravel\Eloquent\Model::class, true)) {
    throw new \LogicException("$relatedClass must extend MongoDB\\Laravel\\Eloquent\\Model to be embedded.");
}

Type guard

function canBeEmbedded(string $class): bool {
    return is_a($class, \MongoDB\Laravel\Eloquent\Model::class, true);
}

Try / catch

try {
    $tags = $document->tags;
} catch (\LogicException $e) {
    if (str_contains($e->getMessage(), 'Related model must be a document model')) {
        logger()->error('embedsMany target is not a document model');
    }
    throw $e;
}

Prevention

Verify the class string passed to embedsOne/embedsMany extends the MongoDB Model
Document that embedded child models must be document models
Use static analysis (e.g. a custom PHPStan rule) on embeds* relation arguments

When it happens

Trigger: Calling embedsOne(NonDocumentModel::class) or embedsMany(NonDocumentModel::class) where the related class extends vanilla Eloquent Model, then instantiating the relation.

Common situations: Pointing an embeds* relation at a shared model class that was written for a SQL connection; copy-pasting relation definitions between projects.

Related errors

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

Appendix: source

Thrown at src/Relations/EmbedsOneOrMany.php:64

    /**
     * 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();
        }
    }

    /** @inheritdoc */
    #[Override]

View on GitHub (pinned to 0634653039)