HumanSignal/label-studio · error · ValueError

No state model registered for entity '{entity_name}'

Error message

No state model registered for entity '{entity_name}'

What it means

During transition execution, the executor needs the entity's current state. If the entity is not a new/unpersisted record and get_state_model_for_entity(entity) returns None (no registered state model), it raises this ValueError.

Source

Thrown at label_studio/fsm/transition_executor.py:86

        current_state=None,
        target_state=None,  # Will be computed
        organization_id=organization_id,
    )

    # Get target_state (can now use entity from context)
    target_state = transition.get_target_state(minimal_context)
    is_side_effect_only = target_state is None

    if is_side_effect_only:
        # No state model needed for side-effect only transitions
        state_model = None
        current_state_object = None
        current_state = None
    else:
        # Get the state model for the entity
        state_model = get_state_model_for_entity(entity)
        if not state_model:
            raise ValueError(f"No state model registered for entity '{entity_name}'")

        # Get current state information directly from state model
        current_state_object = state_model.get_current_state(entity)
        current_state = current_state_object.state if current_state_object else None

    # Build full transition context
    context = TransitionContext(
        entity=entity,
        current_user=user,
        current_state_object=current_state_object,
        current_state=current_state,
        target_state=target_state,
        organization_id=organization_id,
        **context_kwargs,
    )

    logger.info(
        'Executing transition',

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Register a state model for the entity type before executing transitions.
2. Confirm the entity is a real saved Django model instance of the correct type.
3. Check that registry setup runs at startup (correct AppConfig / import).
4. For brand-new entities, verify they follow the expected 'no prior state' code path the executor supports.

Example fix

// before
execute_transition(task, 'complete')  # TaskState not registered
// after
register_state_model(Task, TaskState)
execute_transition(task, 'complete')

from label_studio.fsm.state_registry import get_state_model_for_entity
assert get_state_model_for_entity(entity), f"Register a state model for {entity._meta.model_name} before transitions"

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

try:
    execute_transition(entity, name)
except ValueError as e:
    if f"No state model registered" in str(e):
        register_state_model(type(entity), MyEntityState)
        execute_transition(entity, name)
    else:
        raise

When it happens

Trigger: Executing a transition on a persisted entity whose model type has no FSM state model registered, while the entity IS in the registry branch of the code (i.e. not handled by the initial-state path).

Common situations: Forgetting register_state_model for the entity type; running transitions in tests with mock entities; registration code not executed because the app module wasn't loaded.

Related errors

• No state model found for {entity._meta.model_name} when gett
• No state model found for {entity._meta.model_name} when gett
• No state model found for {entity._meta.model_name} when tran
• No state model registered for {entity._meta.model_name} when
• No state model registered for {entity._meta.model_name} when

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