locustio/locust · error · Exception

You need to install pymongo or at least bson to be able to…

Error message

You need to install pymongo or at least bson to be able to send/receive ObjectIds

What it means

The msgpack RPC protocol supports bson ObjectId fields for distributed-mode messages, but bson is an optional dependency. If the import failed, the fallback ObjectId class raises this Exception when instantiated, telling the user to install pymongo or bson.

Solutions

1. `pip install pymongo` (or `pip install bson`) in the environment running locust distributed mode
2. Install locust with the appropriate extra if available (e.g. locust[pymongo]-style extras or add to requirements)
3. Ensure master AND worker nodes both have bson installed

Example fix

// before
pip install locust  # no bson; distributed ObjectId messages fail
// after
pip install locust pymongo
# or add to requirements.txt: pymongo>=4.0

try:
    import bson  # noqa
except ImportError:
    raise SystemExit("Install pymongo or bson for distributed-mode ObjectId support: pip install pymongo")

def bson_available() -> bool:
    try:
        import bson
        return True
    except ImportError:
        return False

try:
    master = Environment(...)
    master.create_master_runner()
except Exception as e:
    if "pymongo or at least bson" in str(e):
        raise RuntimeError("pip install pymongo on master and workers") from e
    raise

When it happens

Trigger: Running distributed locust (master/worker) with msgpack payloads containing ObjectIds while neither pymongo nor bson is installed; message decode/encode path hits the placeholder class.

Common situations: Minimal installs of locust without the pymongo extra; slim Docker images used for master or worker nodes; environments where bson was uninstalled during dependency cleanup.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• ZMQ interrupted message
• Socket bind failure
• Tried to register listener method for
• use start_worker
• ZMQ interrupted or corrupted message

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

Appendix: source

Thrown at locust/rpc/protocol.py:13

from __future__ import annotations

import datetime

import msgpack

try:
    from bson import ObjectId
except ImportError:

    class ObjectId:  # type: ignore
        def __init__(self, s):
            raise Exception("You need to install pymongo or at least bson to be able to send/receive ObjectIds")


def decode(obj):
    if "__datetime__" in obj:
        obj = datetime.datetime.strptime(obj["as_str"], "%Y%m%dT%H:%M:%S.%f")
    elif "__ObjectId__" in obj:
        obj = ObjectId(obj["as_str"])
    return obj


def encode(obj):
    if isinstance(obj, datetime.datetime):
        return {"__datetime__": True, "as_str": obj.strftime("%Y%m%dT%H:%M:%S.%f")}
    elif isinstance(obj, ObjectId):
        return {"__ObjectId__": True, "as_str": str(obj)}
    return obj

View on GitHub (pinned to f391a716e1)