{"record":{"id":"34f51fcbcf453c11","repo":"apache/pulsar","slug":"could-not-import-user-function-module-s","errorCode":null,"errorMessage":"Could not import User Function Module %s","messagePattern":"Could not import User Function Module (.+?)","errorType":"exception","errorClass":"NameError","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/instance/src/main/python/python_instance.py","lineNumber":231,"sourceCode":"      consumer_args.update(nack_args)\n      if consumer_conf.HasField(\"receiverQueueSize\"):\n        consumer_args[\"receiver_queue_size\"] = consumer_conf.receiverQueueSize.value\n\n      if consumer_conf.isRegexPattern:\n        self.consumers[topic] = self.pulsar_client.subscribe(\n          re.compile(str(topic)), subscription_name,\n          **consumer_args\n        )\n      else:\n        self.consumers[topic] = self.pulsar_client.subscribe(\n          str(topic), subscription_name,\n          **consumer_args\n        )\n\n    function_kclass = util.import_class(os.path.dirname(self.user_code), self.instance_config.function_details.className)\n    if function_kclass is None:\n      Log.critical(\"Could not import User Function Module %s\" % self.instance_config.function_details.className)\n      raise NameError(\"Could not import User Function Module %s\" % self.instance_config.function_details.className)\n    try:\n      self.function_class = function_kclass()\n    except:\n      self.function_purefunction = function_kclass\n\n    self.contextimpl = contextimpl.ContextImpl(self.instance_config, Log, self.pulsar_client,\n                                               self.user_code, self.consumers,\n                                               self.secrets_provider, self.metrics_labels,\n                                               self.state_context, self.stats)\n    # Now launch a thread that does execution\n    self.execution_thread = threading.Thread(target=self.actual_execution)\n    self.execution_thread.start()\n\n    # start proccess spawner health check timer\n    self.last_health_check_ts = time.time()\n    if self.expected_healthcheck_interval > 0:\n      timer = util.FixedTimer(self.expected_healthcheck_interval, self.process_spawner_health_check_timer, name=\"health-check-timer\")\n      timer.start()","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/instance/src/main/python/python_instance.py#L213-L249","documentation":"python_instance.run imports the user's function class via util.import_class using the configured className. If the import returns None (module or class not found), Pulsar logs it as critical and raises NameError('Could not import User Function Module %s'), meaning the Python class specified in functionDetails.className could not be loaded from the user code directory.","triggerScenarios":"className in the function config doesn't match module.ClassName available under the user code path; the user code directory (self.user_code) is wrong or the file isn't distributed; a missing __init__.py or import error inside the module causing the import to fail and return None.","commonSituations":"Typos in the fully qualified class name (e.g. myfunc.MyFunction vs functions/my_function.py); uploading a zip without the expected package structure; module-level import failure due to a missing third-party dependency.","solutions":["Set functionDetails.className to 'module_name.ClassName' exactly matching the file/class in the user code archive.","Verify the user code zip/dir contains the module at its root or correct package path and includes __init__.py files.","Test importing the class locally with the same Python runtime before deploying.","Fix any module-level import errors (missing pip dependencies bundled with the function)."],"exampleFix":"# before (config)\nclassName: myfunc.myfunction  # wrong path, module named my_function\n# after\nclassName: my_function.MyFunction","handlingStrategy":"validation","validationCode":"import importlib, sys\nmod, cls = 'my_function', 'MyFunction'\nassert mod in sys.modules or importlib.util.find_spec(mod), f\"module {mod} missing\"\nassert callable(getattr(importlib.import_module(mod), cls)), f\"class {cls} missing\"","typeGuard":null,"tryCatchPattern":"try:\n    # instance startup handled by framework\n    run_instance()\nexcept NameError as e:\n    logging.critical('user function class not importable: %s', e)\n    sys.exit(3)","preventionTips":["Test import locally with the same Python version before deploy.","Verify zip layout: module files at archive root (or correct package dirs with __init__.py).","Keep className as module.ClassName exactly.","Bundle all third-party deps with the function code."],"tags":["python","pulsar-functions","import-error","deployment"],"backgroundTag":"module-import-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}