{"record":{"id":"2f34c3b6558c20f6","repo":"mlflow/mlflow","slug":"the-custom-metric-definitions-were-serialized-usin","errorCode":null,"errorMessage":"The custom metric definitions were serialized using MLflow {}. Deserializing them with the current version {} might cause mismatches. Please ensure compatibility or consider regenerating the metrics using the current version.","messagePattern":"The custom metric definitions were serialized using MLflow (.+?)\\. Deserializing them with the current version (.+?) might cause mismatches\\. Please ensure compatibility or consider regenerating the metrics using the current version\\.","errorType":"console","errorClass":"UserWarning","httpStatus":null,"severity":"warning","filePath":"mlflow/metrics/genai/genai_metric.py","lineNumber":700,"sourceCode":"\n\ndef _filter_by_field(df, field_name, value):\n    return df[df[field_name] == value]\n\n\ndef _deserialize_genai_metric_args(args_dict):\n    mlflow_version_at_ser = args_dict.pop(\"mlflow_version\", None)\n    fn_name = args_dict.pop(\"fn_name\", None)\n    if fn_name is None or mlflow_version_at_ser is None:\n        raise MlflowException(\n            message=\"The artifact JSON file appears to be corrupted and cannot be deserialized. \"\n            \"Please regenerate the custom metrics and rerun the evaluation. \"\n            \"Ensure that the file is correctly formatted and not tampered with.\",\n            error_code=INTERNAL_ERROR,\n        )\n\n    if mlflow_version_at_ser != VERSION:\n        warnings.warn(\n            f\"The custom metric definitions were serialized using MLflow {mlflow_version_at_ser}. \"\n            f\"Deserializing them with the current version {VERSION} might cause mismatches. \"\n            \"Please ensure compatibility or consider regenerating the metrics \"\n            \"using the current version.\",\n            UserWarning,\n            stacklevel=2,\n        )\n\n    if fn_name == make_genai_metric_from_prompt.__name__:\n        return make_genai_metric_from_prompt(**args_dict)\n\n    examples = args_dict[\"examples\"]\n    if examples is not None:\n        args_dict[\"examples\"] = [EvaluationExample(**example) for example in examples]\n\n    return make_genai_metric(**args_dict)\n\n","sourceCodeStart":682,"sourceCodeEnd":718,"githubUrl":"https://github.com/mlflow/mlflow/blob/6a27f2decc0b76eb1b54af31849784addb357dbc/mlflow/metrics/genai/genai_metric.py#L682-L718","documentation":"A UserWarning raised in _deserialize_genai_metric_args (invoked by retrieve_custom_metrics) when the MLflow version recorded in the serialized custom metric file differs from the currently running MLflow VERSION. The metric definitions were written by a different MLflow version, and deserializing them may produce mismatches in evaluation behavior. MLflow warns rather than failing, since the format is usually compatible.","triggerScenarios":"Calling mlflow.metrics.genai retrieve_custom_metrics (e.g., when running evaluation with stored custom metric definitions) where the `mlflow_version` field in the serialized file != the installed mlflow version.","commonSituations":"Evaluation run in a different environment than the one that created the metrics (CI vs local, upgraded mlflow); custom metrics saved months earlier and replayed after an mlflow upgrade.","solutions":["Regenerate/re-serialize the custom metrics using the current MLflow version","Pin the environment to the MLflow version used at serialization time if regeneration is not possible","Review the metric definitions for compatibility after the version change and re-run evaluation to confirm results"],"exampleFix":"// before\n# metric file serialized with mlflow 2.9.0, env runs mlflow 2.17.0\nmetrics = retrieve_custom_metrics(...)\n// after\n$ pip install mlflow==2.9.0  # match serialization version, recreate metrics\n# then regenerate metrics with the target version\nmetrics = retrieve_custom_metrics(...)","handlingStrategy":"validation","validationCode":"import json, mlflow\nfrom mlflow import VERSION\nwith open(\"custom_metrics.json\") as f:\n    data = json.load(f)\nif data.get(\"mlflow_version\") != VERSION:\n    print(f\"Metric serialized with MLflow {data.get('mlflow_version')}, current is {VERSION} — regenerate metrics or pin mlflow=={data.get('mlflow_version')}\")","typeGuard":null,"tryCatchPattern":"import warnings\nwith warnings.catch_warnings(record=True) as w:\n    warnings.simplefilter(\"always\")\n    metrics = retrieve_custom_metrics(file_path)\n    if any(\"serialized using MLflow\" in str(x.message) for x in w):\n        regenerate_metrics_with_current_version()","preventionTips":["Regenerate custom metric definitions after every MLflow upgrade","Pin the MLflow version used for serialization and deserialization in CI and prod","Store metric definitions in version control so they can be regenerated deterministically"],"tags":["genai","metrics","evaluation","version-compatibility","serialization"],"backgroundTag":"version-mismatch","analyzedSha":"6a27f2decc0b76eb1b54af31849784addb357dbc","analyzedAt":"2026-08-29T20:54:51.419Z","schemaVersion":2},"datasetVersion":"2026-08-29T22:17:34.462Z"}