mlflow/mlflow · error · MlflowException

The prebuilt env '{env_archive_path}' runtime version '{preb

Error message

The prebuilt env '{env_archive_path}' runtime version '{prebuilt_runtime_version}' does not match UDF sandbox runtime version {runtime_version}.

What it means

MLflow verifies that a pre-built (cached) Python environment archive used by spark_udf matches the UDF sandbox's requirements before reusing it. This check compares the MLflow runtime version embedded in the archive against the runtime version of the current sandbox. A mismatch means the archive was built with a different MLflow release than the one executing the UDF, which could yield incompatible dependencies.

Source

Thrown at mlflow/pyfunc/__init__.py:1869

def _verify_prebuilt_env(spark, local_model_path, env_archive_path):
    # Use `[:-7]` to truncate ".tar.gz" in the end
    archive_name = os.path.basename(env_archive_path)[:-7]
    prebuilt_env_sha, prebuilt_runtime_version, prebuilt_platform_machine = archive_name.split("-")[
        -3:
    ]

    python_env = _get_python_env(Path(local_model_path))
    env_sha = _get_virtualenv_name(python_env, local_model_path).split("-")[-1]
    dbconnect_udf_sandbox_info = get_dbconnect_udf_sandbox_info(spark)
    runtime_version = dbconnect_udf_sandbox_info.image_version
    platform_machine = dbconnect_udf_sandbox_info.platform_machine

    if prebuilt_env_sha != env_sha:
        raise MlflowException(
            f"The prebuilt env '{env_archive_path}' does not match the model required environment."
        )
    if prebuilt_runtime_version != runtime_version:
        raise MlflowException(
            f"The prebuilt env '{env_archive_path}' runtime version '{prebuilt_runtime_version}' "
            f"does not match UDF sandbox runtime version {runtime_version}."
        )
    if prebuilt_platform_machine != platform_machine:
        raise MlflowException(
            f"The prebuilt env '{env_archive_path}' platform machine '{prebuilt_platform_machine}' "
            f"does not match UDF sandbox platform machine {platform_machine}."
        )


def _prebuild_env_internal(local_model_path, archive_name, save_path, env_manager):
    env_root_dir = os.path.join(_PREBUILD_ENV_ROOT_LOCATION, archive_name)
    archive_path = os.path.join(save_path, archive_name + ".tar.gz")
    if os.path.exists(env_root_dir):
        shutil.rmtree(env_root_dir)
    if os.path.exists(archive_path):
        os.remove(archive_path)

View on GitHub (pinned to 6a27f2decc)

Solutions

Rebuild the prebuilt env archive with the current MLflow version: call mlflow.pyfunc.build_model_env(model_uri, save_path) in the Databricks runtime, then pass the new archive path to spark_udf.
Or downgrade/align MLflow to the version that built the archive (check with tar -tzf or the archive metadata).
Remove the stale archive to prevent accidental reuse.

Example fix

# before
spark_udf(spark, model_uri, prebuilt_env_uri='/mnt/cache/env-mlflow-2.9.tar.gz')  # MLflow 2.10 installed
# after
mlflow.pyfunc.build_model_env(model_uri, save_path='/mnt/cache')  # rebuild with MLflow 2.10
spark_udf(spark, model_uri, prebuilt_env_uri='/mnt/cache/<new-archive>.tar.gz')

Defensive patterns

Strategy: validation

Validate before calling

import mlflow
archive = 'dbfs:/mnt/cache/env.tar.gz'
# rebuild if the archive was built under a different MLflow version
assert mlflow.__version__ == expected_version, f"MLflow {mlflow.__version__} != version that built the env; rebuild with build_model_env()"

Try / catch

try:
    udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=archive)
except MlflowException as e:
    if 'runtime version' in str(e):
        new_archive = mlflow.pyfunc.build_model_env(model_uri, save_path='/mnt/cache')
        udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=new_archive)
    else:
        raise

Prevention

Rebuild the prebuilt env archive whenever the MLflow version changes
Pin the MLflow version together with the archive path in config
Never share archive paths across MLflow upgrades without invalidation

When it happens

Trigger: Calling mlflow.pyfunc.spark_udf(..., prebuilt_env_uri=<archive>) where the archive was produced with build_model_env under a different MLflow version than the one running spark_udf (e.g., the archive is stale after upgrading MLflow).

Common situations: Upgrading the MLflow package on the cluster or Databricks Connect client while reusing an old prebuilt env archive from shared storage; pinning a prebuilt_env_uri in code across an MLflow version bump.

Related errors

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