What causes "Failed to create state record for {transition_name}" in HumanSignal/label-studio?

Inspect logs around the apply_transition call to find why success was False (validation error vs. DB error).

HumanSignal/label-studio · error · ValueError

Failed to create state record for {transition_name}

Error message

Failed to create state record for {transition_name}

What it means

After running the transition, the executor checks whether a new state record was successfully persisted via the state manager. If the state-manager apply/record call returns success=False, it raises ValueError indicating the state record creation failed for that transition.

Source

Thrown at label_studio/fsm/transition_executor.py:157

    # Check if this transition forces state record creation (for audit trails)
    force_state_record = getattr(transition, '_force_state_record', False)

    # Use context.reason if provided (caller override), otherwise use transition's default
    reason = context.reason if context.reason else transition.get_reason(context)

    success = state_manager_class.transition_state(
        entity=entity,
        new_state=target_state,
        transition_name=transition.transition_name,
        user=user,
        context=transition_context_data,
        reason=reason,
        force_state_record=force_state_record,
    )

    if not success:
        raise ValueError(f'Failed to create state record for {transition_name}')

    # Get the newly created state record via StateManager
    state_record = state_manager_class.get_current_state_object(entity)

    # Phase 3: Finalize the transition
    transition.finalize(context, state_record)

    return state_record

View on GitHub (pinned to 0b49e9b539)

Solutions

Inspect logs around the apply_transition call to find why success was False (validation error vs. DB error).
Run the transition inside a debug shell and call state_manager methods directly to surface the underlying exception.
Ensure the state model and registry are correctly configured for the entity.
Check for race conditions: reload the entity and retry the transition if another process mutated it.

Example fix

// before
success = state_manager.apply_transition(...)
if not success:
    raise ValueError(f'Failed to create state record for {transition_name}')
// after
result = state_manager.apply_transition_with_detail(...)  # returns error info
if not result.success:
    logger.error('state record failed: %s', result.reason)
    raise ValueError(f'Failed to create state record for {transition_name}: {result.reason}')

Defensive patterns

Strategy: try-catch

Try / catch

try:
    execute_transition(entity, name, **kwargs)
except ValueError as e:
    if str(e).startswith('Failed to create state record'):
        logger.exception('State record creation failed; entity=%s transition=%s', entity.pk, name)
        # inspect entity state, rollback or retry once
    else:
        raise

Prevention

Wrap transitions in transactions and surface underlying DB errors to logs.
Monitor for repeated success=False returns from apply_transition.
Keep the state model's required fields satisfiable by the transition context.

When it happens

Trigger: The underlying state_manager.apply_transition call returns False — typically because validation failed, the state model save failed, or force_state_record was False and no state record was created.

Common situations: Database constraint violations or transaction rollback silently swallowed into success=False; concurrent modification of the entity; transition finalize logic mutating state in a way the manager rejects; misconfigured state model for the entity.

Related errors

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