{"record":{"id":"9c8b9eb11c299e14","repo":"mlflow/mlflow","slug":"the-prebuilt-env-env-archive-path-runtime-vers","errorCode":null,"errorMessage":"The prebuilt env '{env_archive_path}' runtime version '{prebuilt_runtime_version}' does not match UDF sandbox runtime version {runtime_version}.","messagePattern":"The prebuilt env '(.+?)' runtime version '(.+?)' does not match UDF sandbox runtime version (.+?)\\.","errorType":"exception","errorClass":"MlflowException","httpStatus":null,"severity":"error","filePath":"mlflow/pyfunc/__init__.py","lineNumber":1869,"sourceCode":"def _verify_prebuilt_env(spark, local_model_path, env_archive_path):\n    # Use `[:-7]` to truncate \".tar.gz\" in the end\n    archive_name = os.path.basename(env_archive_path)[:-7]\n    prebuilt_env_sha, prebuilt_runtime_version, prebuilt_platform_machine = archive_name.split(\"-\")[\n        -3:\n    ]\n\n    python_env = _get_python_env(Path(local_model_path))\n    env_sha = _get_virtualenv_name(python_env, local_model_path).split(\"-\")[-1]\n    dbconnect_udf_sandbox_info = get_dbconnect_udf_sandbox_info(spark)\n    runtime_version = dbconnect_udf_sandbox_info.image_version\n    platform_machine = dbconnect_udf_sandbox_info.platform_machine\n\n    if prebuilt_env_sha != env_sha:\n        raise MlflowException(\n            f\"The prebuilt env '{env_archive_path}' does not match the model required environment.\"\n        )\n    if prebuilt_runtime_version != runtime_version:\n        raise MlflowException(\n            f\"The prebuilt env '{env_archive_path}' runtime version '{prebuilt_runtime_version}' \"\n            f\"does not match UDF sandbox runtime version {runtime_version}.\"\n        )\n    if prebuilt_platform_machine != platform_machine:\n        raise MlflowException(\n            f\"The prebuilt env '{env_archive_path}' platform machine '{prebuilt_platform_machine}' \"\n            f\"does not match UDF sandbox platform machine {platform_machine}.\"\n        )\n\n\ndef _prebuild_env_internal(local_model_path, archive_name, save_path, env_manager):\n    env_root_dir = os.path.join(_PREBUILD_ENV_ROOT_LOCATION, archive_name)\n    archive_path = os.path.join(save_path, archive_name + \".tar.gz\")\n    if os.path.exists(env_root_dir):\n        shutil.rmtree(env_root_dir)\n    if os.path.exists(archive_path):\n        os.remove(archive_path)\n","sourceCodeStart":1851,"sourceCodeEnd":1887,"githubUrl":"https://github.com/mlflow/mlflow/blob/6a27f2decc0b76eb1b54af31849784addb357dbc/mlflow/pyfunc/__init__.py#L1851-L1887","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\nspark_udf(spark, model_uri, prebuilt_env_uri='/mnt/cache/env-mlflow-2.9.tar.gz')  # MLflow 2.10 installed\n# after\nmlflow.pyfunc.build_model_env(model_uri, save_path='/mnt/cache')  # rebuild with MLflow 2.10\nspark_udf(spark, model_uri, prebuilt_env_uri='/mnt/cache/<new-archive>.tar.gz')","handlingStrategy":"validation","validationCode":"import mlflow\narchive = 'dbfs:/mnt/cache/env.tar.gz'\n# rebuild if the archive was built under a different MLflow version\nassert mlflow.__version__ == expected_version, f\"MLflow {mlflow.__version__} != version that built the env; rebuild with build_model_env()\"","typeGuard":null,"tryCatchPattern":"try:\n    udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=archive)\nexcept MlflowException as e:\n    if 'runtime version' in str(e):\n        new_archive = mlflow.pyfunc.build_model_env(model_uri, save_path='/mnt/cache')\n        udf = mlflow.pyfunc.spark_udf(spark, model_uri, prebuilt_env_uri=new_archive)\n    else:\n        raise","preventionTips":["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"],"tags":["mlflow","spark-udf","version-mismatch","prebuilt-env"],"backgroundTag":"runtime-version-mismatch","analyzedSha":"6a27f2decc0b76eb1b54af31849784addb357dbc","analyzedAt":"2026-08-29T20:54:51.419Z","schemaVersion":2},"datasetVersion":"2026-08-29T22:17:34.462Z"}