mlflow/mlflow · error · MlflowException

If 'prebuilt_env_uri' parameter is set, 'env_manager' parame

Error message

If 'prebuilt_env_uri' parameter is set, 'env_manager' parameter must be either None, 'virtualenv', or 'uv'.

What it means

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.

Source

Thrown at mlflow/pyfunc/__init__.py:2235

        IntegerType,
        LongType,
        MapType,
        StringType,
    )
    from pyspark.sql.types import StructType as SparkStructType

    from mlflow.pyfunc.spark_model_cache import SparkModelCache
    from mlflow.utils._spark_utils import _SparkDirectoryDistributor

    is_spark_connect = is_spark_connect_mode()
    # Used in test to force install local version of mlflow when starting a model server
    mlflow_home = os.environ.get("MLFLOW_HOME")
    openai_env_vars = mlflow.openai.model._OpenAIEnvVar.read_environ()
    mlflow_testing = _MLFLOW_TESTING.get_raw()

    if prebuilt_env_uri:
        if env_manager not in (None, _EnvManager.VIRTUALENV, _EnvManager.UV):
            raise MlflowException(
                "If 'prebuilt_env_uri' parameter is set, 'env_manager' parameter must "
                "be either None, 'virtualenv', or 'uv'."
            )
        env_manager = _EnvManager.VIRTUALENV
    else:
        env_manager = env_manager or _EnvManager.LOCAL

    _EnvManager.validate(env_manager)

    if is_spark_connect:
        is_spark_in_local_mode = False
    else:
        # Check whether spark is in local or local-cluster mode
        # this case all executors and driver share the same filesystem
        is_spark_in_local_mode = spark.conf.get("spark.master").startswith("local")

    is_dbconnect_mode = is_databricks_connect(spark)
    if prebuilt_env_uri is not None and not is_dbconnect_mode:

View on GitHub (pinned to 6a27f2decc)

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.

Example fix

# before
spark_udf(spark, model_uri, prebuilt_env_uri='dbfs:/mnt/cache/env.tar.gz', env_manager='conda')
# after
spark_udf(spark, model_uri, prebuilt_env_uri='dbfs:/mnt/cache/env.tar.gz')

Defensive patterns

Strategy: validation

Validate before calling

if prebuilt_env_uri and env_manager not in (None, 'virtualenv', 'uv'):
    raise ValueError(f"env_manager={env_manager!r} is incompatible with prebuilt_env_uri; use None/virtualenv/uv")

Try / catch

try:
    udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=uri, env_manager=env_manager)
except MlflowException as e:
    if "'env_manager' parameter must" in str(e):
        udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=uri)
    else:
        raise

Prevention

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

When it happens

Trigger: Calling mlflow.pyfunc.spark_udf(..., prebuilt_env_uri='dbfs:/...', env_manager='local') or env_manager='conda'.

Common situations: 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.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/7e0154d5a7037f0f. Report an issue: GitHub.