apache/beam · error · ValueError

Input should be a module object, got {str(module)} instead

Error message

Input should be a module object, got {str(module)} instead

What it means

register_pickle_by_value() in Beam's vendored cloudpickle records a module so its code is serialized by value rather than by reference. The library raises ValueError immediately if the argument is not a types.ModuleType instance, because only real module objects carry the __name__/module semantics it needs to register.

Source

Thrown at sdks/python/apache_beam/internal/cloudpickle/cloudpickle.py:235

    By default, functions and classes that are attributes of an importable
    module are to be pickled by reference, that is relying on re-importing
    the attribute from the module at load time.

    If `register_pickle_by_value(module)` is called, all its functions and
    classes are subsequently to be pickled by value, meaning that they can
    be loaded in Python processes where the module is not importable.

    This is especially useful when developing a module in a distributed
    execution environment: restarting the client Python process with the new
    source code is enough: there is no need to re-install the new version
    of the module on all the worker nodes nor to restart the workers.

    Note: this feature is considered experimental. See the cloudpickle
    README.md file for more details and limitations.
    """
  if not isinstance(module, types.ModuleType):
    raise ValueError(
        f"Input should be a module object, got {str(module)} instead")
  # In the future, cloudpickle may need a way to access any module registered
  # for pickling by value in order to introspect relative imports inside
  # functions pickled by value. (see
  # https://github.com/cloudpipe/cloudpickle/pull/417#issuecomment-873684633).
  # This access can be ensured by checking that module is present in
  # sys.modules at registering time and assuming that it will still be in
  # there when accessed during pickling. Another alternative would be to
  # store a weakref to the module. Even though cloudpickle does not implement
  # this introspection yet, in order to avoid a possible breaking change
  # later, we still enforce the presence of module inside sys.modules.
  if module.__name__ not in sys.modules:
    raise ValueError(
        f"{module} was not imported correctly, have you used an "
        "`import` statement to access it?")
  _PICKLE_BY_VALUE_MODULES.add(module.__name__)

View on GitHub (pinned to 12126d8942)

Solutions

  1. Pass the module object itself, e.g. register_pickle_by_value(my_module), not a string.
  2. If you only have the name string, do importlib.import_module(name) first.
  3. Verify with isinstance(x, types.ModuleType) before calling.
  4. Register the module right after a normal `import`, not via from-import of individual symbols.

Example fix

// before
register_pickle_by_value('mymodule')
// after
import mymodule
register_pickle_by_value(mymodule)
Defensive patterns

Strategy: type-guard

Validate before calling

import types
if not isinstance(mod, types.ModuleType):
    raise TypeError('register_pickle_by_value requires a module object')

Type guard

def is_module(x) -> bool:
    import types
    return isinstance(x, types.ModuleType)

Try / catch

try:
    register_pickle_by_value(mod)
except ValueError as e:
    if 'Input should be a module object' in str(e):
        register_pickle_by_value(importlib.import_module(str(mod)))
    else:
        raise

Prevention

When it happens

Trigger: Calling apache_beam.internal.cloudpickle.cloudpickle.register_pickle_by_value() with a string module name (e.g. 'my_module'), a class, function, package path, or any non-module object.

Common situations: Passing a module name as a string instead of the module object; using __main__-defined helpers accidentally; calling with a dynamically imported object that is actually a class or function, not the module.

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/d2b7123a8057221c. Report an issue: GitHub.