Suggest "Open Documentation" when toolchain not found

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## {{releaseVersion}} - {{releaseDate}}
 
+### Fixed
+
+- Suggest "Open Documentation" when toolchain not found ([#1939](https://github.com/swiftlang/vscode-swift/pull/1939))
+
 ## 2.14.0 - 2025-11-11
 
 ### Added

src/ui/ToolchainSelection.ts

@@ -79,7 +79,7 @@ async function selectToolchainFolder() {
  * @returns true if the user made a selection (and potentially updated toolchain settings), false if they dismissed the dialog
  */
 export async function showToolchainError(folder?: vscode.Uri): Promise<boolean> {
-    let selected: "Remove From Settings" | "Select Toolchain" | undefined;
+    let selected: "Remove From Settings" | "Select Toolchain" | "Open Documentation" | undefined;
     const folderName = folder ? `${FolderContext.uriName(folder)}: ` : "";
     if (configuration.path) {
         selected = await vscode.window.showErrorMessage(
@@ -90,6 +90,7 @@ export async function showToolchainError(folder?: vscode.Uri): Promise<boolean>
     } else {
         selected = await vscode.window.showErrorMessage(
             `${folderName}Unable to automatically discover your Swift toolchain. Either install a toolchain from Swift.org or provide the path to an existing toolchain.`,
+            "Open Documentation",
             "Select Toolchain"
         );
     }
@@ -100,6 +101,13 @@ export async function showToolchainError(folder?: vscode.Uri): Promise<boolean>
     } else if (selected === "Select Toolchain") {
         await selectToolchain();
         return true;
+    } else if (selected === "Open Documentation") {
+        void vscode.env.openExternal(
+            vscode.Uri.parse(
+                "https://docs.swift.org/vscode/documentation/userdocs/supported-toolchains"
+            )
+        );
+        return false;
     }
     return false;
 }

userdocs/userdocs.docc/Articles/Topics/supported-toolchains.md

@@ -22,6 +22,10 @@ Debugging with `lldb-dap`  | 6.0
 
 The Swift extension automatically detects installations of the Swift toolchain in your environment. It looks for a `swift` binary available in `PATH` and, if one cannot be found, prompts you to [install a toolchain from Swift.org](https://www.swift.org/install).
 
+<div class="warning" markdown="1">
+If you install a toolchain or Swiftly while VS Code is open, you likely will need to fully quit VS Code and then reopen it. This makes sure the extension host gets the updated PATH so that extension can find the toolchain.
+</div>
+
 If you have multiple Swift toolchains installed on your system, use the command `Swift: Select Toolchain...` to tell the extension which toolchain to use. The command shows you a list of all the toolchains that VS Code found on your system and lets you switch between them.
 
 @Video(