HumanSignal/label-studio · error · StateManagerError

No state model registered for {entity._meta.model_name} when

Error message

No state model registered for {entity._meta.model_name} when getting state history

What it means

get_state_history looks up the entity's state model in the registry and raises StateManagerError when none is registered, using the 'state history' phrasing. The state history API endpoint (FSMEntityHistoryAPI.get_queryset) calls this, so requesting history for an entity type without a registered state model surfaces this error instead of an empty list.

Source

Thrown at label_studio/fsm/state_manager.py:442

                },
                exc_info=True,
            )
            raise StateManagerError(f'Failed to transition state: {e}') from e

    @classmethod
    def get_state_history(cls, entity: Model) -> QuerySet[BaseState]:
        """
        Get complete state history for an entity.

        Args:
            entity: Entity to get history for

        Returns:
            QuerySet of state records ordered by most recent first
        """
        state_model = get_state_model_for_entity(entity)
        if not state_model:
            raise StateManagerError(
                f'No state model registered for {entity._meta.model_name} when getting state history'
            )

        return state_model.get_state_history(entity)

    @classmethod
    def get_states_in_time_range(
        cls, entity: Model, start_time: datetime, end_time: Optional[datetime] = None
    ) -> List[BaseState]:
        """
        Get states within a time range using UUID7 time-based queries.

        Args:
            entity: Entity to get states for
            start_time: Start of time range
            end_time: End of time range (defaults to now)

        Returns:

View on GitHub (pinned to 0b49e9b539)

Solutions

Only request history for entity types present in state_model_registry.get_all_models() (the endpoint's own list check).
Register a state model for the entity if it should have FSM history.
Guard script/API callers with get_state_model_for_entity(entity) and treat None as 'no history available'.
Verify deployment edition: if the state model is enterprise-only, ensure LSE components are installed and registration runs.

Example fix

// before
history = StateManager.get_state_history(my_custom_model_instance)  # raises: No state model registered

// after
if get_state_model_for_entity(my_custom_model_instance):
    history = StateManager.get_state_history(my_custom_model_instance)
else:
    history = BaseState.objects.none()

Defensive patterns

Strategy: type-guard

Validate before calling

from fsm.registry import state_model_registry, get_state_model_for_entity

entity_type_ok = entity._meta.model_name in state_model_registry.get_all_models()
entity_ok = get_state_model_for_entity(entity) is not None
if entity_type_ok and entity_ok:
    history = StateManager.get_state_history(entity)

Type guard

def has_state_history(entity) -> bool:
    from fsm.registry import get_state_model_for_entity
    return get_state_model_for_entity(entity) is not None

Try / catch

from fsm.state_manager import StateManager, StateManagerError
try:
    qs = StateManager.get_state_history(entity)
except StateManagerError as e:
    if 'No state model registered' in str(e):
        qs = BaseState.objects.none()
    else:
        raise

Prevention

Request history only for entity types in state_model_registry.get_all_models()
Register state models for any entity that should expose history via the API
Guard custom dashboards/scripts so non-FSM models return an empty history instead of erroring

When it happens

Trigger: Calling StateManager.get_state_history(entity) for an unregistered model, or hitting GET /api/fsm/entities/{entity_type}/{entity_id}/history/ (after passing the endpoint's registry-list check) where the per-entity registry lookup still fails — e.g., registry populated differently at request time, or custom entity types added to permission_map but never registered as state models.

Common situations: Building a custom UI that lists history for entity types assumed FSM-managed; community edition serving history requests for enterprise-only registered state models; management scripts iterating over many model types including non-FSM ones.

Related errors

AI-assisted analysis of HumanSignal/label-studio@0b49e9b539 (2026-08-29). Data as JSON: /api/errors/c26a947b3e112f15. Report an issue: GitHub.