HumanSignal/label-studio · error · ValueError

Invalid entity name: {entity_name}

Error message

Invalid entity name: {entity_name}

What it means

FSMAPIMixin.get_permission_required looks up the URL kwarg entity_name in the view's permission_map and raises ValueError(f'Invalid entity name: {entity_name}') when there is no entry. This is a configuration/routing error: the FSM endpoint was called with an entity name that has no permission mapping registered.

Source

Thrown at label_studio/fsm/api.py:34

)
from fsm.state_manager import get_state_manager
from fsm.transitions import ModelChangeTransition, TransitionValidationError
from pydantic import ValidationError as PydanticValidationError
from rest_framework import generics, status
from rest_framework.exceptions import NotFound, PermissionDenied, ValidationError
from rest_framework.filters import OrderingFilter
from rest_framework.pagination import PageNumberPagination
from rest_framework.response import Response

logger = logging.getLogger(__name__)


class FSMAPIMixin:
    def get_permission_required(self):
        entity_name = self.kwargs['entity_name']
        permission = self.permission_map.get(entity_name)
        if not permission:
            raise ValueError(f'Invalid entity name: {entity_name}')
        return permission

    def get_entity(self):
        state_model = get_state_model(self.kwargs['entity_name'])
        if not state_model:
            raise NotFound()
        entity_model = state_model.get_entity_model()
        entity = get_object_or_404(entity_model.objects, id=self.kwargs['entity_id'])
        try:
            self.check_object_permissions(self.request, entity)
        except PermissionDenied as e:
            # Return 404 instead of 403 to avoid leaking entity existence
            raise NotFound() from e
        return entity


class FSMEntityHistoryPagination(PageNumberPagination):
    page_size_query_param = 'page_size'

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Correct the entity_name in the request URL to a registered entity (e.g. 'task').
2. Add the missing entity_name -> permission entry to the view's permission_map.
3. Verify state_model_registry registrations match the permission_map keys.
4. Add a route/serializer validation or a friendly 404 for unknown entity_name before permission lookup.
5. Update client code/tests that hardcode old entity names.

Example fix

// before
class FSMHistoryView(FSMAPIMixin):
    permission_map = {"task": all_permissions.tasks_view}  # request uses entity_name="annotation"
// after
class FSMHistoryView(FSMAPIMixin):
    permission_map = {"task": all_permissions.tasks_view, "annotation": all_permissions.annotations_view}

def entity_is_configured(entity_name: str, permission_map: dict, registry) -> bool:
    return entity_name in permission_map and entity_name in registry.get_all_models()

try:
    perm = view.get_permission_required()
except ValueError as e:
    logger.error('FSM entity misconfigured: %s', e)
    return Response({'detail': f'Unknown entity: {view.kwargs["entity_name"]}'}, status=404)

When it happens

Trigger: Requesting any FSM mixin endpoint (e.g. history list/transition endpoints) with an entity_name URL segment that is not a key of the view class's permission_map — e.g. a typo or an entity type that was never registered on that view.

Common situations: Hardcoded client URLs referencing renamed entities; a new state model was registered in state_model_registry but permission_map on the view was not updated; typos in route parameters (e.g. 'taskss' vs 'task'); API version drift between frontend and backend.

Related errors

• transition_name: Unknown transition for this entity
• LABEL_STUDIO_HOST must be a subpath if DOMAIN_FROM_REQUEST i
• SECURE_PROXY_SSL_HEADER must be configured as "<header>,<val
• "file_upload_ids" parameter must be a list of integers
• transition_name: Transition is auto-triggered and cannot be

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