{"record":{"id":"d8f87d5de1c44a6a","repo":"apache/beam","slug":"module-was-not-imported-correctly-have-you-used-an-import","errorCode":null,"errorMessage":"{module} was not imported correctly, have you used an `import` statement to access it?","messagePattern":"(.+?) was not imported correctly, have you used an `import` statement to access it\\?","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/internal/cloudpickle/cloudpickle.py","lineNumber":248,"sourceCode":"\n    Note: this feature is considered experimental. See the cloudpickle\n    README.md file for more details and limitations.\n    \"\"\"\n  if not isinstance(module, types.ModuleType):\n    raise ValueError(\n        f\"Input should be a module object, got {str(module)} instead\")\n  # In the future, cloudpickle may need a way to access any module registered\n  # for pickling by value in order to introspect relative imports inside\n  # functions pickled by value. (see\n  # https://github.com/cloudpipe/cloudpickle/pull/417#issuecomment-873684633).\n  # This access can be ensured by checking that module is present in\n  # sys.modules at registering time and assuming that it will still be in\n  # there when accessed during pickling. Another alternative would be to\n  # store a weakref to the module. Even though cloudpickle does not implement\n  # this introspection yet, in order to avoid a possible breaking change\n  # later, we still enforce the presence of module inside sys.modules.\n  if module.__name__ not in sys.modules:\n    raise ValueError(\n        f\"{module} was not imported correctly, have you used an \"\n        \"`import` statement to access it?\")\n  _PICKLE_BY_VALUE_MODULES.add(module.__name__)\n\n\ndef unregister_pickle_by_value(module):\n  \"\"\"Unregister that the input module should be pickled by value.\"\"\"\n  if not isinstance(module, types.ModuleType):\n    raise ValueError(\n        f\"Input should be a module object, got {str(module)} instead\")\n  if module.__name__ not in _PICKLE_BY_VALUE_MODULES:\n    raise ValueError(f\"{module} is not registered for pickle by value\")\n  else:\n    _PICKLE_BY_VALUE_MODULES.remove(module.__name__)\n\n\ndef list_registry_pickle_by_value():\n  return _PICKLE_BY_VALUE_MODULES.copy()","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/internal/cloudpickle/cloudpickle.py#L230-L266","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure a real `import mymodule` has executed before registering.","If building a module dynamically, set sys.modules[module.__name__] = module before calling.","Do not remove the module from sys.modules while it is registered.","If using mocks, patch the real imported module rather than a synthetic ModuleType."],"exampleFix":"// before\nm = types.ModuleType('mymod')\nregister_pickle_by_value(m)\n// after\nm = types.ModuleType('mymod')\nsys.modules['mymod'] = m\nregister_pickle_by_value(m)","handlingStrategy":"validation","validationCode":"import sys, types\nassert isinstance(mod, types.ModuleType) and mod.__name__ in sys.modules, 'module must be imported before registering'","typeGuard":"def is_imported_module(x) -> bool:\n    import sys, types\n    return isinstance(x, types.ModuleType) and x.__name__ in sys.modules","tryCatchPattern":"try:\n    register_pickle_by_value(mod)\nexcept ValueError as e:\n    if 'not imported correctly' in str(e):\n        sys.modules[mod.__name__] = mod\n        register_pickle_by_value(mod)\n    else:\n        raise","preventionTips":["Do a real `import` before registering.","Never delete modules from sys.modules while registered.","For dynamic modules, insert into sys.modules before registering."],"tags":["python","apache-beam","cloudpickle","import"],"backgroundTag":"module-init-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}