locustio/locust · error · ValueError

The following user classes have the same class name: {}

Error message

The following user classes have the same class name: {}

What it means

Two user classes in different modules may share the same class name, making `user_classes_by_name` lookups ambiguous. `_validate_user_class_name_uniqueness` compares the set of names against the list and raises ValueError listing the offending full names (module.ClassName).

Source

Thrown at locust/env.py:293

        for u in self.user_classes:
            u.weight = 1
            user_tasks: list[TaskSet | Callable] = []
            tasks_frontier = u.tasks
            while len(tasks_frontier) != 0:
                t = tasks_frontier.pop()
                if isinstance(t, TaskHolder):
                    tasks_frontier.extend(t.tasks)
                elif callable(t):
                    if t not in user_tasks:
                        user_tasks.append(t)
                else:
                    raise ValueError("Unrecognized task type in user")
            u.tasks = user_tasks

    def _validate_user_class_name_uniqueness(self):
        # Validate there's no class with the same name but in different modules
        if len({user_class.__name__ for user_class in self.user_classes}) != len(self.user_classes):
            raise ValueError(
                "The following user classes have the same class name: {}".format(
                    ", ".join(map(methodcaller("fullname"), self.user_classes))
                )
            )

    def _validate_shape_class_instance(self):
        if self.shape_class is not None and not isinstance(self.shape_class, LoadTestShape):
            raise ValueError(
                f"shape_class should be instance of LoadTestShape or subclass LoadTestShape, but got: {self.shape_class}"
            )

    @property
    def user_classes_by_name(self) -> dict[str, type[User]]:
        return {u.__name__: u for u in self.user_classes}

View on GitHub (pinned to f391a716e1)

Solutions

1. Rename one of the conflicting classes so names are unique
2. If duplicates come from imports, import only one version and remove the other from the user_classes list
3. Use distinct, descriptive class names per locustfile

Example fix

// before
# module_a.py: class User(User): ...
# module_b.py: class User(User): ...
env = Environment(user_classes=[a.User, b.User])
// after
# module_b.py: class ModuleBUser(User): ...
env = Environment(user_classes=[a.User, b.ModuleBUser])

names = [c.__name__ for c in user_classes]
assert len(names) == len(set(names)), f"duplicate user class names: {names}"

try:
    env = Environment(user_classes=user_classes)
except ValueError as e:
    if "same class name" in str(e):
        print(e)  # lists offending fullnames; rename one class
    raise

When it happens

Trigger: Passing two different classes named e.g. `WebsiteUser` (imported from different modules) into the same Environment or locust run.

Common situations: Importing a locustfile's user class into another locustfile and running both; test suites combining fixture user classes with identical names; monorepos with per-service user classes named generically like `User`.

Related errors

• Unrecognized task type in user
• There are no users with weight > 0.
• TaskSet.run() is a method used internally by Locust, and you
• No tag name was supplied
• Invalid time span format

AI-assisted analysis of locustio/locust@f391a716e1 (2026-08-29). Data as JSON: /api/errors/1c9575371d410ea8. Report an issue: GitHub.