Multiple classes found for path error on reload with model relationships

[Raido-Tokuyama]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

models.py

from datetime import datetime
from typing import List, Optional
from sqlmodel import SQLModel, Field, Relationship

class RestaurantMenu(SQLModel, table=True):
    __tablename__ = "restaurant_menu"
    __table_args__ = {"extend_existing": True}

    restaurant_id: int = Field(foreign_key="restaurant.id", primary_key=True)
    menu_id: int = Field(foreign_key="menu.id", primary_key=True)
    created_at: datetime = Field(default_factory=datetime.now, nullable=False)

class Restaurant(SQLModel, table=True):
    __tablename__ = "restaurant"
    __table_args__ = {"extend_existing": True}

    id: int = Field(default=None, primary_key=True)
    name: str = Field(max_length=100, nullable=False)
    address: str = Field(max_length=200, nullable=False)
    created_at: datetime = Field(default_factory=datetime.now, nullable=False)
    updated_at: datetime = Field(default_factory=datetime.now, nullable=False)
    menus: List["Menu"] = Relationship(back_populates="restaurants", link_model=RestaurantMenu)

class Menu(SQLModel, table=True):
    __tablename__ = "menu"
    __table_args__ = {"extend_existing": True}

    id: int = Field(default=None, primary_key=True)
    name: str = Field(max_length=100, nullable=False)
    price: int = Field(nullable=False)
    description: Optional[str] = Field(max_length=500, nullable=True, description="メニューの説明")
    created_at: datetime = Field(default_factory=datetime.now, nullable=False)
    updated_at: datetime = Field(default_factory=datetime.now, nullable=False)
    restaurants: List["Restaurant"] = Relationship(back_populates="menus", link_model=RestaurantMenu)

database.py

import os
from sqlmodel import SQLModel, create_engine, Session, select
from dotenv import load_dotenv
from models.models import Restaurant, Menu, RestaurantMenu
import streamlit as st

load_dotenv()
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///restaurant.db")

@st.cache_resource
def get_engine():
    engine = create_engine(DATABASE_URL, echo=False)
    SQLModel.metadata.create_all(engine)
    return engine

def get_session():
    engine = get_engine()
    with Session(engine) as session:
        yield session

def create_initial_data():
    engine = get_engine()
    with Session(engine) as session:
        if not session.exec(select(Restaurant)).first():
            restaurant = Restaurant(name="Sample Restaurant", address="Tokyo")
            session.add(restaurant)
            session.commit()
            session.refresh(restaurant)

            menus = [
                Menu(name="Hamburger Set", price=1200, description="Hamburger"),
                Menu(name="Pasta Set", price=1000, description="Pasta")
            ]
            session.add_all(menus)
            session.commit()
            session.refresh(menus[0])
            session.refresh(menus[1])

            relations = [
                RestaurantMenu(restaurant_id=restaurant.id, menu_id=menu.id)
                for menu in menus
            ]
            session.add_all(relations)
            session.commit()

main.py

import streamlit as st
from sqlmodel import select
st.set_page_config(page_title="Restaurant Menu System", layout="wide")

from database import get_session, create_initial_data
from models.models import Restaurant

st.title("Restaurant Menu System")

# Create initial data
create_initial_data()

# Get session
session = next(get_session())

# Display restaurant list
restaurants = session.exec(select(Restaurant)).all()

# Select restaurant from sidebar
selected_restaurant = st.sidebar.selectbox(
    "Select a restaurant",
    restaurants,
    format_func=lambda x: x.name
)

if selected_restaurant:
    st.header(f"{selected_restaurant.name}")
    st.write(f"Address: {selected_restaurant.address}")

    restaurant = session.exec(
        select(Restaurant).where(Restaurant.id == selected_restaurant.id)
    ).one()

    # Display menu
    st.subheader("Menu")
    for menu in restaurant.menus:
            st.write(f"- {menu.name}")

Description

When using Streamlit with SQLModel, errors occur when reloading the application after making code changes to model files. The errors are related to model registration and mapper initialization.

Even though __table_args__ = {"extend_existing": True} is specified in all model classes, which should normally allow redefinitions of table mappings without error, the application still throws an InvalidRequestError on reload.

A comment from a Streamlit contributor suggests that this may be caused by SQLModel's internal registry persisting across script reloads. Streamlit has a mechanism to clean stateful modules between runs, and similar support might be possible if SQLModel provided a way to reset its registry. If such a mechanism already exists, I would appreciate any guidance.

Environment

• Python: 3.13
• Streamlit: 1.43.2
• SQLModel: 0.0.24
• OS: macOS

Steps to Reproduce

1. Create a minimal project with the following structure:

• app/
  • models/
    • models.py # Contains all model definitions
  • database.py # Database connection setup
  • main.py # Streamlit application

2. Define models with relationships:

# models.py

class Restaurant(SQLModel, table=True):
    __table_args__ = {"extend_existing": True}

    id: int = Field(default=None, primary_key=True)
    menus: List["Menu"] = Relationship(back_populates="restaurants", link_model=RestaurantMenu)

class Menu(SQLModel, table=True):
    __table_args__ = {"extend_existing": True}

    id: int = Field(default=None, primary_key=True)
    restaurants: List["Restaurant"] = Relationship(back_populates="menus", link_model=RestaurantMenu)

class RestaurantMenu(SQLModel, table=True):
    __table_args__ = {"extend_existing": True}

    restaurant_id: int = Field(foreign_key="restaurant.id", primary_key=True)
    menu_id: int = Field(foreign_key="menu.id", primary_key=True)

3. Run the Streamlit application:

streamlit run app/main.py

4. Make any code change to models.py (e.g., add a comment or modify a field description)

Note: Simply reloading the page without code changes does NOT trigger the error
The error occurs when reloading after making code modifications

5. Make another code change and reload again

Expected Behavior

The application should properly handle reloading and maintain the relationships between models when code changes are made and the page is reloaded.

Actual Behavior

After First Code Change and Reload

sqlalchemy.exc.InvalidRequestError: Multiple classes found for path "[ClassName]" in the registry of this declarative base. Please use a fully module-qualified path.

After Second Code Change and Reload

sqlalchemy.exc.InvalidRequestError: One or more mappers failed to initialize - can't proceed with initialization of other mappers. Triggering mapper: 'Mapper[Restaurant(restaurant)]'. Original exception was: Multiple classes found for path "Menu" in the registry of this declarative base. Please use a fully module-qualified path.

Key observations:

1. Errors only occur when reloading after code changes
2. Simple page refreshes without code changes work normally
3. First reload after code change produces a simpler error about multiple classes
4. Second reload after code change produces a error involving mapper initialization
5. Both errors indicate issues with multiple class registrations

Operating System

macOS

Operating System Details

Sequoia 15.3.1

SQLModel Version

0.0.24

Python Version

3.13.2

Additional Context

No response