SeaQL/sea-orm · error

called `BelongsTo::unwrap()` on an `Unloaded` value

Error message

called `BelongsTo::unwrap()` on an `Unloaded` value

What it means

BelongsTo<E>::unwrap() returns the related model only when the relation is Loaded; it panics here because the variant is Unloaded — the belonging relation was never fetched (no .with(...)/find_related load ran before unwrap), so no model exists to move out. This flags an API-usage ordering mistake, not a missing database row.

Source

Thrown at src/entity/compound/belongs_to.rs:137

            Self::Unloaded => None,
        }
    }

    /// Convert into an `Option<ModelEx>`
    pub fn into_option(self) -> Option<E::ModelEx> {
        match self {
            Self::Loaded(model) => Some(*model),
            Self::Unloaded => None,
        }
    }

    /// # Panics
    ///
    /// Panics if called on an `Unloaded` value.
    pub fn unwrap(self) -> E::ModelEx {
        match self {
            Self::Loaded(model) => *model,
            Self::Unloaded => panic!("called `BelongsTo::unwrap()` on an `Unloaded` value"),
        }
    }
}

impl<E> BelongsTo<Option<E>>
where
    E: EntityTrait,
{
    /// Return true if this optional relation was loaded and no model was found.
    pub fn is_not_found(&self) -> bool {
        matches!(self, Self::Loaded(None))
    }

    /// Return true if this optional relation holds no model — i.e. it is either
    /// `Unloaded` or was loaded with no match (`is_not_found`).
    pub fn is_unloaded_or_not_found(&self) -> bool {
        matches!(self, Self::Unloaded | Self::Loaded(None))
    }

View on GitHub (pinned to e29bcd1b41)

Solutions

1. Eager-load the relation: use .with(rel::Entity) on the query
2. Call .load(db).await? on the BelongsTo before unwrap()
3. Use try_get() / is_loaded() checks instead of unwrap()

Example fix

// before
let parent = user.company.unwrap();
// after
let user = user::Entity::load().filter_by_id(id).with(company::Entity).one(db).await?;
let parent = user.company.unwrap();

if rel.is_loaded() { /* safe to access */ } else { /* load first */ }

fn loaded<E>(b: &BelongsTo<E>) -> Option<&E::ModelEx> { b.as_loaded() }

let parent = company.load(db).await?.unwrap();

When it happens

Trigger: Calling .unwrap() on a BelongsTo<E> field of a model whose relation was not loaded via .with(...) / load() before access.

Common situations: Fetching an entity without eager-loading the belongs_to relation then immediately reading the field; forgetting to include the relation in the .with() chain; loading failing silently.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• called `BelongsTo::unwrap()` on a `Loaded(None)` value
• index out of bounds: the HasMany is Unloaded (index: {index}
• called `HasOne::unwrap()` on an `Unloaded` value
• called `HasOne::unwrap()` on a `Loaded(None)` value
• Cannot unwrap ActiveValue::NotSet

AI-assisted analysis of SeaQL/sea-orm@e29bcd1b41 (2026-09-10). Data as JSON: /api/errors/1e9037bcd3caa6fb. Report an issue: GitHub.