Update the error/warning messages for stale/invalid lockfiles

src/python/pants/backend/python/util_rules/pex.py

@@ -436,15 +436,7 @@ async def build_pex(
 
         requirements_file_digest_contents = await Get(DigestContents, PathGlobs, globs)
         metadata = LockfileMetadata.from_lockfile(requirements_file_digest_contents[0].content)
-        if not metadata.is_valid_for(
-            request.requirements.lockfile_hex_digest,
-            request.interpreter_constraints,
-            python_setup.interpreter_universe,
-        ):
-            if python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.error:
-                raise ValueError("Invalid lockfile provided. [TODO(#12314): Improve message]")
-            elif python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.warn:
-                logger.warning("%s", "Invalid lockfile provided. [TODO(#12314): Improve message]")
+        _validate_metadata(metadata, request, python_setup)
 
         requirements_file_digest = await Get(Digest, PathGlobs, globs)
 
@@ -453,15 +445,7 @@ async def build_pex(
         argv.extend(["--requirement", file_content.path])
 
         metadata = LockfileMetadata.from_lockfile(file_content.content)
-        if not metadata.is_valid_for(
-            request.requirements.lockfile_hex_digest,
-            request.interpreter_constraints,
-            python_setup.interpreter_universe,
-        ):
-            if python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.error:
-                raise ValueError("Invalid lockfile provided. [TODO(#12314): Improve message]")
-            elif python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.warn:
-                logger.warning("%s", "Invalid lockfile provided. [TODO(#12314): Improve message]")
+        _validate_metadata(metadata, request, python_setup)
 
         requirements_file_digest = await Get(Digest, CreateDigest([file_content]))
     else:
@@ -515,6 +499,31 @@ async def build_pex(
     )
 
 
+def _validate_metadata(
+    metadata: LockfileMetadata, request: PexRequest, python_setup: PythonSetup
+) -> None:
+    if metadata.is_valid_for(
+        request.requirements.lockfile_hex_digest,
+        request.interpreter_constraints,
+        python_setup.interpreter_universe,
+    ):
+        return None
+
+    message = (
+        f"Invalid lockfile for PEX request `{request.output_filename}`."
+        "\n\n"
+        "If your requirements or your project's interpreter constraints have changed since the "
+        "lockfile was generated, you can follow the instructions in the header of the lockfile to "
+        "regenerate it. Otherwise, ensure your interpreter constraints setting is compatible with "
+        "the constraints specified in the lockfile."
+    )
+
+    if python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.error:
+        raise ValueError(message)
+    elif python_setup.invalid_lockfile_behavior == InvalidLockfileBehavior.warn:
+        logger.warning("%s", message)
+
+
 def _build_pex_description(request: PexRequest) -> str:
     if request.description:
         return request.description

src/python/pants/backend/python/util_rules/pex_test.py

@@ -547,7 +547,7 @@ def test_error_on_invalid_lockfile_with_path(rule_runner: RuleRunner) -> None:
 
 def test_warn_on_invalid_lockfile_with_path(rule_runner: RuleRunner, caplog) -> None:
     _run_pex_for_lockfile_test(rule_runner, True, actual="1bad", expected="900d", behavior="warn")
-    assert "Invalid lockfile provided." in caplog.text
+    assert "Invalid lockfile for PEX request" in caplog.text
 
 
 def test_ignore_on_invalid_lockfile_with_path(rule_runner: RuleRunner, caplog) -> None:
@@ -569,7 +569,7 @@ def test_error_on_invalid_lockfile_with_content(rule_runner: RuleRunner) -> None
 
 def test_warn_on_invalid_lockfile_with_content(rule_runner: RuleRunner, caplog) -> None:
     _run_pex_for_lockfile_test(rule_runner, False, actual="1bad", expected="900d", behavior="warn")
-    assert "Invalid lockfile provided." in caplog.text
+    assert "Invalid lockfile for PEX request" in caplog.text
 
 
 def test_no_warning_on_valid_lockfile_with_content(rule_runner: RuleRunner, caplog) -> None: