Eager loading a `BelongsToMany` relationship raises a NotImplementedError

[circulon]

Migrated from: MasoniteFramework/orm#962
Original author: @bedus-creation
Originally opened: 2026-04-14
Original state: closed

---

Describe the bug

Eager loading a BelongsToMany relationship raises a NotImplementedError indicating that the related_result method is not implemented.

---

To Reproduce

import sys
from types import ModuleType

from masoniteorm.connections import ConnectionResolver
from masoniteorm.models import Model
from masoniteorm.relationships import belongs_to_many
from masoniteorm.schema import Schema

DATABASES = {
    "default": "sqlite",
    "sqlite": {
        "driver": "sqlite",
        "database": "database.sqlite",
    }
}
DB = ConnectionResolver().set_connection_details(DATABASES)

# Mock Masonite ORM config to allow single-file use without config/database.py
config_module = ModuleType('config')
database_module = ModuleType('database')
database_module.DATABASES = DATABASES
database_module.DB = DB
config_module.database = database_module
sys.modules['config'] = config_module
sys.modules['config.database'] = database_module


# ─── Schema Setup ─────────────────────────────────────────────────────────
schema = Schema(connection="sqlite", connection_details=DATABASES)

if schema.has_table("post_tag"): schema.drop("post_tag")
if schema.has_table("tags"): schema.drop("tags")
if schema.has_table("posts"): schema.drop("posts")

with schema.create("posts") as table:
    table.increments("id")
    table.string("title")
    table.text("content").nullable()
    table.timestamps()

with schema.create("tags") as table:
    table.increments("id")
    table.string("name")
    table.timestamps()

with schema.create("post_tag") as table:
    table.increments("id")
    table.integer("post_id").unsigned()
    table.integer("tag_id").unsigned()

# ─── Models ───────────────────────────────────────────────────────────────
class Post(Model):
    @belongs_to_many("post_id", "tag_id", table="post_tag")
    def tags(self):
        return Tag

class Tag(Model):
    @belongs_to_many("tag_id", "post_id", table="post_tag")
    def posts(self):
        return Post

class PostTag(Model):
    __table__ = "post_tag"
    __timestamps__ = False

# ─── Seeding Data ─────────────────────────────────────────────────────────
tag1 = Tag.create({"name": "Python"})
tag2 = Tag.create({"name": "ORM"})
post = Post.create({"title": "A Standalone Script", "content": "It works!"})

PostTag.create({"post_id": post.id, "tag_id": tag1.id})
PostTag.create({"post_id": post.id, "tag_id": tag2.id})

# ─── Query ────────────────────────────────────────────────────────────────
print("\n[!] Eager loading tags for Post:")
posts = Post.with_("tags").get()

for p in posts:
    print(f"- Post: {p.title}")
    for t in p.tags:
        print(f"  - Tag: {t.name}")

Error

NotImplementedError: BelongsToMany relationship does not implement the 'related_result' method