install: explain unsupported bun.lock version and suggest 'bun upgrade'

src/install/lockfile/bun.lock.rs

@@ -1626,10 +1626,23 @@ pub fn parse_into_binary_lockfile(
     };
 
     let Some(lockfile_version) = Version::from_int(lockfile_version_num) else {
-        log.add_error(
+        log.add_range_error_fmt_with_notes(
             Some(source),
-            lockfile_version_expr.loc,
-            b"Unknown lockfile version",
+            bun_ast::Range {
+                loc: lockfile_version_expr.loc,
+                ..Default::default()
+            },
+            Box::new([bun_ast::range_data(
+                None,
+                bun_ast::Range::NONE,
+                b"Run 'bun upgrade' to update to the latest version of Bun",
+            )]),
+            format_args!(
+                "Unsupported lockfile version {}. This lockfile was likely created by a newer version of Bun. (This is Bun v{}, which supports lockfile versions up to {}.)",
+                lockfile_version_num,
+                bun_core::Global::package_json_version,
+                Version::CURRENT as u32,
+            ),
         );
         return Err(ParseError::UnknownLockfileVersion);
     };

test/cli/install/bun-lock.test.ts

@@ -825,3 +825,45 @@ it("escapes quotes and newlines in requested version literals when writing yarn.
   // No yarn.lock line is forged from the version literal's contents.
   expect(lines.filter(line => line.trimStart().startsWith('resolved "http://injected.example'))).toEqual([]);
 });
+
+it("prints an actionable error for a lockfile version newer than this build supports", async () => {
+  const { packageDir, packageJson } = await registry.createTestDir();
+
+  await write(
+    packageJson,
+    JSON.stringify({
+      name: "future-lockfile",
+      dependencies: {},
+    }),
+  );
+
+  await write(
+    join(packageDir, "bun.lock"),
+    JSON.stringify({
+      lockfileVersion: 99,
+      workspaces: {
+        "": {
+          name: "future-lockfile",
+        },
+      },
+      packages: {},
+    }),
+  );
+
+  const { exited, stdout, stderr } = spawn({
+    cmd: [bunExe(), "install"],
+    cwd: packageDir,
+    env,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [out, err] = await Promise.all([stdout.text(), stderr.text()]);
+
+  expect(err).toContain("Unsupported lockfile version 99");
+  expect(err).toContain("newer version of Bun");
+  expect(err).toContain("Run 'bun upgrade'");
+  // the old message gave no hint at all
+  expect(err).not.toContain("Unknown lockfile version");
+  expect(await exited).toBe(0);
+});