apache/beam · error · ValueError

ReadFromMongDB coll param must be specified as a string

Error message

ReadFromMongDB coll param must be specified as a string

What it means

ReadFromMongoDB.__init__ validates that the coll (collection) parameter is a Python str and raises ValueError otherwise. The collection name is forwarded to _BoundedMongoSource and must be a valid string name.

Solutions

Pass the collection name as a str, e.g. coll='users'.
If you have a pymongo Collection object, pass its .name attribute.
Coerce/validate config-sourced values: str(value) after a None check, or .decode() for bytes.
Fix argument order so the intended value reaches coll.

Example fix

// before
coll = mongo_db['users']
p = ReadFromMongoDB(uri=uri, db='mydb', coll=coll)
// after
p = ReadFromMongoDB(uri=uri, db='mydb', coll=coll.name)

Defensive patterns

Strategy: type-guard

Validate before calling

if not isinstance(coll, str) or not coll:
    raise ValueError('coll must be a non-empty string')

Type guard

def is_coll_name(v) -> bool:
    return isinstance(v, str) and bool(v)

Try / catch

try:
    t = ReadFromMongoDB(uri=uri, db=db, coll=coll)
except ValueError as e:
    raise ConfigError(f'bad Mongo source config: {e}') from e

Prevention

Pass collection.name when starting from a pymongo Collection object.
Validate collection names at config load time.
Use keyword arguments to avoid positional mix-ups.

When it happens

Trigger: Calling ReadFromMongoDB(uri=..., db='mydb', coll=<non-string>) — e.g. coll=None, a bytes value, or a pymongo Collection object passed by mistake.

Common situations: Passing a pymongo collection object instead of its name; unset config variable yielding None; bytes from a config parser.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/7c432e04645595bb. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/io/mongodbio.py:155

      projection: A list of field names that should be returned in the result
        set or a dict specifying the fields to include or exclude.
      extra_client_params(dict): Optional `MongoClient
        <https://api.mongodb.com/python/current/api/pymongo/mongo_client.html>`_
        parameters.
      bucket_auto (bool): If :data:`True`, use MongoDB `$bucketAuto` aggregation
        to split collection into bundles instead of `splitVector` command,
        which does not work with MongoDB Atlas.
        If :data:`False` (the default), use `splitVector` command for bundling.

    Returns:
      :class:`~apache_beam.transforms.ptransform.PTransform`
    """
    if extra_client_params is None:
      extra_client_params = {}
    if not isinstance(db, str):
      raise ValueError("ReadFromMongDB db param must be specified as a string")
    if not isinstance(coll, str):
      raise ValueError(
          "ReadFromMongDB coll param must be specified as a string")
    self._mongo_source = _BoundedMongoSource(
        uri=uri,
        db=db,
        coll=coll,
        filter=filter,
        projection=projection,
        extra_client_params=extra_client_params,
        bucket_auto=bucket_auto,
    )

  def expand(self, pcoll):
    return pcoll | iobase.Read(self._mongo_source)


class _ObjectIdRangeTracker(OrderedPositionRangeTracker):
  """RangeTracker for tracking mongodb _id of bson ObjectId type."""
  def position_to_fraction(

View on GitHub (pinned to 12126d8942)