apache/beam · error · ValueError

{module} was not imported correctly, have you used an `impor

Error message

{module} was not imported correctly, have you used an `import` statement to access it?

What it means

After confirming the argument is a module, register_pickle_by_value() enforces that the module is present in sys.modules, so cloudpickle can later introspect it during pickling. If the module object was never properly imported (or was created/removed without registration in sys.modules), ValueError is raised.

Source

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

    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__)


def unregister_pickle_by_value(module):
  """Unregister that the input module should be pickled by value."""
  if not isinstance(module, types.ModuleType):
    raise ValueError(
        f"Input should be a module object, got {str(module)} instead")
  if module.__name__ not in _PICKLE_BY_VALUE_MODULES:
    raise ValueError(f"{module} is not registered for pickle by value")
  else:
    _PICKLE_BY_VALUE_MODULES.remove(module.__name__)


def list_registry_pickle_by_value():
  return _PICKLE_BY_VALUE_MODULES.copy()

View on GitHub (pinned to 12126d8942)

Solutions

  1. Ensure a real `import mymodule` has executed before registering.
  2. If building a module dynamically, set sys.modules[module.__name__] = module before calling.
  3. Do not remove the module from sys.modules while it is registered.
  4. If using mocks, patch the real imported module rather than a synthetic ModuleType.

Example fix

// before
m = types.ModuleType('mymod')
register_pickle_by_value(m)
// after
m = types.ModuleType('mymod')
sys.modules['mymod'] = m
register_pickle_by_value(m)
Defensive patterns

Strategy: validation

Validate before calling

import sys, types
assert isinstance(mod, types.ModuleType) and mod.__name__ in sys.modules, 'module must be imported before registering'

Type guard

def is_imported_module(x) -> bool:
    import sys, types
    return isinstance(x, types.ModuleType) and x.__name__ in sys.modules

Try / catch

try:
    register_pickle_by_value(mod)
except ValueError as e:
    if 'not imported correctly' in str(e):
        sys.modules[mod.__name__] = mod
        register_pickle_by_value(mod)
    else:
        raise

Prevention

When it happens

Trigger: Passing a module-like object not registered in sys.modules, e.g. a module created via importlib.util module_from_spec without inserting into sys.modules, or a module deleted with del sys.modules[name] before registering.

Common situations: Dynamic module loading in tests; stubbing modules in test setups that replace sys.modules entries; constructing fake module objects (types.ModuleType('x')) without sys.modules['x'] = m.

Related errors

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