locustio/locust · error · ValueError

shape_class should be instance of LoadTestShape or subclass

Error message

shape_class should be instance of LoadTestShape or subclass LoadTestShape, but got: {self.shape_class}

What it means

Environment.shape_class must be an instance of LoadTestShape (not a class). If a non-None value is passed that is not a LoadTestShape instance, this ValueError is raised.

Source

Thrown at locust/env.py:301

                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

Instantiate the shape class: `Environment(..., shape_class=MyShape())`
Verify the object passed derives from locust.shape.LoadTestShape
Fix references that pass the class object instead of an instance

Example fix

// before
env = Environment(user_classes=[MyUser], shape_class=MyShape)
// after
env = Environment(user_classes=[MyUser], shape_class=MyShape())

Defensive patterns

Strategy: type-guard

Validate before calling

from locust import LoadTestShape

shape = MyShape()
assert isinstance(shape, LoadTestShape), "shape_class must be a LoadTestShape instance"
env = Environment(user_classes=[MyUser], shape_class=shape)

Type guard

from locust import LoadTestShape

def is_valid_shape(shape) -> bool:
    return isinstance(shape, LoadTestShape)

Try / catch

try:
    env = Environment(user_classes=[MyUser], shape_class=MyShape())
except ValueError as e:
    if "shape_class" in str(e):
        raise RuntimeError("Pass an instance: shape_class=MyShape()") from e
    raise

Prevention

Always instantiate: `shape_class=MyShape()` not `MyShape`
Keep imports from locust.shape / locust import LoadTestShape consistent
Test Environment construction in CI

When it happens

Trigger: Passing the LoadTestShape subclass itself (e.g. `shape_class=MyShape`) instead of an instance (`shape_class=MyShape()`); passing a completely unrelated object.

Common situations: Confusion between classes and instances when wiring a load shape in scripts or tests; refactors that pass the class after previously instantiating it.

Related errors

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