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 states in time range

What it means

StateManager.get_states_in_time_range raises StateManagerError when the entity's model has no FSM state model registered in the state model registry. The time-range query (UUID7-based) can only run against a registered state model, so without registration it refuses to proceed.

Source

Thrown at label_studio/fsm/state_manager.py:465

    @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:
            List of states within the time range
        """
        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 states in time range'
            )

        return state_model.get_states_in_range(entity, start_time, end_time or datetime.now())

    @classmethod
    def invalidate_cache(cls, entity: Model):
        """Invalidate cached state for an entity"""
        cache_key = cls.get_cache_key(entity)
        fsm_cache = get_fsm_cache()
        fsm_cache.delete(cache_key)
        organization_id = CurrentContext.get_organization_id()
        logger.info(
            'FSM: Cache invalidated',
            extra={
                'event': 'fsm.cache_invalidated',
                'entity_type': entity._meta.label_lower,
                'entity_id': entity.pk,

View on GitHub (pinned to 0b49e9b539)

Solutions

Register a state model for the entity type via the FSM registry (register_state_model) before querying.
Confirm the entity is an actual Django model instance of the registered type, not a mock or unrelated model.
If the entity should not have FSM states, guard the call: only query time ranges for entity types known to have state models.
Check get_state_model_for_entity / the registry setup at app startup for typos or missing imports that prevent registration.

Example fix

// before
states = StateManager.get_states_in_time_range(some_model, start, end)
# after
from label_studio.fsm.state_registry import get_state_model_for_entity
if get_state_model_for_entity(some_model):
    states = StateManager.get_states_in_time_range(some_model, start, end)

Defensive patterns

Strategy: validation

Validate before calling

from label_studio.fsm.state_registry import get_state_model_for_entity
if not get_state_model_for_entity(entity):
    raise LookupError(f'No FSM state model for {entity._meta.model_name}; register it before querying history')

Type guard

def has_state_model(entity) -> bool:
    return get_state_model_for_entity(entity) is not None

Try / catch

try:
    states = StateManager.get_states_in_time_range(entity, start, end)
except StateManagerError as e:
    logger.warning('FSM time-range query unavailable: %s', e)
    states = []

Prevention

Register every entity's state model in the app's ready()/startup module.
Add a startup assertion that iterates expected models and verifies registration.
Never pass mock/unsaved models into StateManager classmethods in tests.

When it happens

Trigger: Calling StateManager.get_states_in_time_range(entity, start, end) for a model type that was never passed to register_state_model (or on an unsaved/mock entity whose model_name has no registry entry).

Common situations: Developers add a new model but forget the state model registration in app initialization; tests call get_states_in_time_range on plain mock models (e.g. MagicMock) whose model_name isn't registered; typos in the registered model_name.

Related errors

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