peer-review

mendonk · mendonk · commit 47946fc1ceb4 · 2026-05-01T15:49:27.000-04:00
diff --git a/docs/docs/Support/troubleshooting.mdx b/docs/docs/Support/troubleshooting.mdx
@@ -83,6 +83,10 @@ If you experience an error from the `webrtcvad` package, run `uv pip install web
 
 ## Langflow Desktop installation issues
 
+The following issues can occur when Langflow Desktop installs or updates its bundled Langflow OSS instance.
+
+To view Langflow Desktop logs, see [Desktop logs](/logging#desktop-logs).
+
 ### Protocol buffers (protoc) required for Intel-based Macs
 
 If you're installing Langflow on an Intel-based Mac, you may encounter installation errors if Protocol Buffers Compiler (`protoc`) is not installed.
@@ -93,15 +97,9 @@ To resolve this issue, install `protoc` using `brew install protobuf`.
 
 For more information, including alternative installation methods, see the [Protocol buffers installation documentation](https://protobuf.dev/installation/).
 
-### C++ build tools required for Langflow Desktop on Windows
-
-The following issues can occur when Langflow Desktop is setting up or installing Langflow OSS automatically during first-time setup or updates.
-
-To view Langflow Desktop logs, see [Desktop logs](/logging#desktop-logs).
-
-### Failed to install Langflow OSS: Unable to sanity check Langflow OSS version
+### Langflow Installation Error: langflow-install-error
 
-Desktop installed Langflow OSS but couldn't verify the installation. You may see the error message: `Langflow Installation Error: langflow-install-error` or other `Langflow Installation Error:` messages.
+Langflow Desktop installed Langflow OSS but couldn't verify the installation. You may see error messages like `Langflow Installation Error: langflow-install-error`.
 
 To resolve this error, do the following:
 
@@ -113,9 +111,9 @@ To resolve this error, do the following:
 
 If the issue persists, ensure you have installed Python version 3.10 or later, and it is accessible by your Langflow installation. If the Python version is correct, try reinstalling Langflow Desktop from [langflow.org/desktop](https://langflow.org/desktop).
 
-### Langflow OSS health check failed
+### Langflow Health Check Error: Timeout after 80 attempts
 
-Desktop installed Langflow OSS but the OSS backend isn't responding to health checks. You can get health check error messages like `Langflow Health Check Error: Timeout after 80 attempts - Langflow did not become ready`.
+Langflow Desktop installed Langflow OSS but the OSS backend isn't responding to health checks. You may see an error message like `Langflow Health Check Error: Timeout after 80 attempts - Langflow did not become ready`.
 
 To resolve this error, do the following:
 
@@ -135,20 +133,46 @@ The following error messages mean that Langflow Desktop can't locate the `uv` ex
 
 To resolve this error, do the following:
 
-1. Verify `uv` is installed by running `uv --version` in a terminal.
-2. If `uv` is not found, install `uv` using the instructions in "[Windows] All automatic installation strategies failed" below, or see the [uv installation guide](https://github.com/astral-sh/uv#installation).
-3. If `uv` is installed but not found, add it to your PATH environment variable:
-   * Windows: Add `%USERPROFILE%\.cargo\bin` to your PATH. In PowerShell, run:
+1. In a terminal verify `uv` is installed by running `uv --version`.
+2. Based on the output, install `uv` or add it to your PATH:
+
+   <Tabs>
+   <TabItem value="not-installed" label="uv is not installed (command not found)" default>
+
+   Install `uv` using one of the following methods:
+
+   * Windows (PowerShell):
+     ```powershell
+     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+     ```
+   * macOS or Linux:
+     ```bash
+     curl -LsSf https://astral.sh/uv/install.sh | sh
+     ```
+   * Any platform (pip):
+     ```bash
+     pip install uv
+     ```
+
+   </TabItem>
+   <TabItem value="not-found" label="uv is installed but not found by Langflow Desktop">
+
+   Add `uv` to your PATH so Langflow Desktop can locate it:
+
+   * Windows: In PowerShell, run:
      ```powershell
      [System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.cargo\bin", "User")
      ```
-   * macOS or Linux: Add `~/.cargo/bin` to your PATH in `~/.bashrc` or `~/.zshrc`.
+   * macOS or Linux: Add `~/.local/bin` to your PATH in `~/.bashrc` or `~/.zshrc`.
 
-4. Restart Langflow Desktop.
+   </TabItem>
+   </Tabs>
 
-### Failed to create Python virtual environment
+3. Restart Langflow Desktop.
+
+### Python Environment Error: Creation failed
 
-Desktop failed to create the Python virtual environment required for Langflow OSS. You may see the error message: `Python Environment Error: error_dns`, `Python Environment Error: Creation failed:` followed by error details, or other `Python Environment Error:` messages.
+Langflow Desktop failed to create the Python virtual environment required for Langflow OSS. You may see error messages like `Python Environment Error: Creation failed:` followed by error details, `Python Environment Error: error_dns`, or other `Python Environment Error:` messages.
 
 To resolve this error, do the following:
 
@@ -162,35 +186,30 @@ To resolve this error, do the following:
 
 If the issue persists, ensure Python version >=3.10 is installed and accessible, or reinstall Langflow Desktop from [langflow.org/desktop](https://langflow.org/desktop).
 
-### Failed to sanity check Python execution
-
-Desktop created the Python virtual environment but couldn't verify that Python is working correctly. You may see the error message: `Python Environment Error: Python check failed:` followed by error details, or other `Python Environment Error:` messages.
+### Python Environment Error: Python check failed
 
-To resolve this error, see [Failed to create Python virtual environment](#failed-to-create-python-virtual-environment).
+Langflow Desktop created the Python virtual environment but couldn't verify that Python is working correctly. You may see error messages like `Python Environment Error: Python check failed:` followed by error details, or other `Python Environment Error:` messages.
 
-### Failed to install Langflow OSS: Xcode Command Line Tools are not installed
+To resolve this error, see [Python Environment Error: Creation failed](#python-environment-error-creation-failed).
 
-Langflow Desktop requires [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/) to install Langflow OSS on macOS. You may see the error message: `Langflow Installation Error: error_xcode` or a detailed message with the title `Xcode Command Line Tools required!`.
+### Langflow Installation Error: error_xcode
 
-To install XCode Command Line Tools manually, do the following:
+Langflow Desktop requires [Xcode Command Line Tools](https://developer.apple.com/xcode/resources/) to install Langflow OSS on macOS. You may see error messages like `Langflow Installation Error: error_xcode` or a detailed message with the title `Xcode Command Line Tools required!`.
 
-1. Open a terminal and run `xcode-select --install`.
-2. **The installation may take over 20 minutes**.
-To start the installation process, in the popup dialogue, click **Install**.
-3. Verify the installation by opening a new terminal and running `xcode-select -p`.
-   The command should return a path like `/Library/Developer/CommandLineTools`.
-4. Restart Langflow Desktop.
+To resolve this error, do the following:
 
-If the manual installation doesn't resolve the issue, download Xcode Command Line Tools from [Apple Developer Downloads](https://developer.apple.com/download/all/), and install the `.dmg` file manually.
+1. Install [Xcode Command Line Tools](https://developer.apple.com/xcode/resources/).
+2. Launch Xcode at least once. Xcode performs additional setup on first startup that other tools such as Git, VS Code, and Langflow Desktop depend on.
+3. Restart Langflow Desktop.
 
-### Failed to install Langflow OSS: Missing C++ Build Tools
+### Langflow Installation Error: error_cpp
 
 Microsoft Windows installations of Langflow Desktop require a C++ compiler that may not be present on your system.
-If you receive a `C++ Build Tools Required!` error, see the error message `Langflow Installation Error: error_cpp`, or see a detailed message with the title "C++ Build Tools required!", follow the on-screen prompt to install Microsoft C++ Build Tools, or install [Microsoft Visual Studio](https://visualstudio.microsoft.com/downloads/).
+If you receive a `Langflow Installation Error: error_cpp` error or a detailed message with the title `C++ Build Tools required!`, follow the on-screen prompt to install Microsoft C++ Build Tools, or install [Microsoft Visual Studio](https://visualstudio.microsoft.com/downloads/).
 
-### All automatic installation strategies failed on Windows
+### UV Installation Error: uv-manual-install-required
 
-Langflow Desktop tried multiple methods to automatically install `uv` but all attempts failed. Desktop requires `uv` to manage Python packages and virtual environments. You may see the error message: `UV Installation Error: uv-manual-install-required` or a detailed manual installation message.
+Langflow Desktop tried multiple methods to automatically install `uv` but all attempts failed. Desktop requires `uv` to manage Python packages and virtual environments. You may see error messages like `UV Installation Error: uv-manual-install-required` or a detailed manual installation message.
 
 To resolve this error, do the following:
 
