{"record":{"id":"7e0154d5a7037f0f","repo":"mlflow/mlflow","slug":"if-prebuilt-env-uri-parameter-is-set-env-manag","errorCode":null,"errorMessage":"If 'prebuilt_env_uri' parameter is set, 'env_manager' parameter must be either None, 'virtualenv', or 'uv'.","messagePattern":"If 'prebuilt_env_uri' parameter is set, 'env_manager' parameter must be either None, 'virtualenv', or 'uv'\\.","errorType":"exception","errorClass":"MlflowException","httpStatus":null,"severity":"error","filePath":"mlflow/pyfunc/__init__.py","lineNumber":2235,"sourceCode":"        IntegerType,\n        LongType,\n        MapType,\n        StringType,\n    )\n    from pyspark.sql.types import StructType as SparkStructType\n\n    from mlflow.pyfunc.spark_model_cache import SparkModelCache\n    from mlflow.utils._spark_utils import _SparkDirectoryDistributor\n\n    is_spark_connect = is_spark_connect_mode()\n    # Used in test to force install local version of mlflow when starting a model server\n    mlflow_home = os.environ.get(\"MLFLOW_HOME\")\n    openai_env_vars = mlflow.openai.model._OpenAIEnvVar.read_environ()\n    mlflow_testing = _MLFLOW_TESTING.get_raw()\n\n    if prebuilt_env_uri:\n        if env_manager not in (None, _EnvManager.VIRTUALENV, _EnvManager.UV):\n            raise MlflowException(\n                \"If 'prebuilt_env_uri' parameter is set, 'env_manager' parameter must \"\n                \"be either None, 'virtualenv', or 'uv'.\"\n            )\n        env_manager = _EnvManager.VIRTUALENV\n    else:\n        env_manager = env_manager or _EnvManager.LOCAL\n\n    _EnvManager.validate(env_manager)\n\n    if is_spark_connect:\n        is_spark_in_local_mode = False\n    else:\n        # Check whether spark is in local or local-cluster mode\n        # this case all executors and driver share the same filesystem\n        is_spark_in_local_mode = spark.conf.get(\"spark.master\").startswith(\"local\")\n\n    is_dbconnect_mode = is_databricks_connect(spark)\n    if prebuilt_env_uri is not None and not is_dbconnect_mode:","sourceCodeStart":2217,"sourceCodeEnd":2253,"githubUrl":"https://github.com/mlflow/mlflow/blob/6a27f2decc0b76eb1b54af31849784addb357dbc/mlflow/pyfunc/__init__.py#L2217-L2253","documentation":"prebuilt_env_uri archives can only be materialized with the virtualenv (or uv) environment manager, so spark_udf restricts env_manager when a prebuilt env is supplied. Passing env_manager='local' or any other value together with prebuilt_env_uri raises this MlflowException.","triggerScenarios":"Calling mlflow.pyfunc.spark_udf(..., prebuilt_env_uri='dbfs:/...', env_manager='local') or env_manager='conda'.","commonSituations":"Copy-pasting an old spark_udf call that set env_manager='conda' and adding prebuilt_env_uri; a generic wrapper that forwards env_manager blindly.","solutions":["Remove the env_manager argument when using prebuilt_env_uri (it defaults to virtualenv automatically).","Explicitly pass env_manager='virtualenv' or 'uv'.","If you need conda or local mode, drop prebuilt_env_uri."],"exampleFix":"# before\nspark_udf(spark, model_uri, prebuilt_env_uri='dbfs:/mnt/cache/env.tar.gz', env_manager='conda')\n# after\nspark_udf(spark, model_uri, prebuilt_env_uri='dbfs:/mnt/cache/env.tar.gz')","handlingStrategy":"validation","validationCode":"if prebuilt_env_uri and env_manager not in (None, 'virtualenv', 'uv'):\n    raise ValueError(f\"env_manager={env_manager!r} is incompatible with prebuilt_env_uri; use None/virtualenv/uv\")","typeGuard":null,"tryCatchPattern":"try:\n    udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=uri, env_manager=env_manager)\nexcept MlflowException as e:\n    if \"'env_manager' parameter must\" in str(e):\n        udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=uri)\n    else:\n        raise","preventionTips":["Omit env_manager whenever prebuilt_env_uri is set","Centralize spark_udf calls in a wrapper that validates the argument combination","Document that prebuilt envs only support virtualenv/uv"],"tags":["mlflow","spark-udf","invalid-argument-combination","prebuilt-env","env-manager"],"backgroundTag":"incompatible-parameters","analyzedSha":"6a27f2decc0b76eb1b54af31849784addb357dbc","analyzedAt":"2026-08-29T20:54:51.419Z","schemaVersion":2},"datasetVersion":"2026-08-29T22:17:34.462Z"}