docs: troubleshoot desktop errors from telemetry

docs/docs/Support/troubleshooting.mdx

@@ -81,6 +81,12 @@ sudo apt-get install gcc
 
 If you experience an error from the `webrtcvad` package, run `uv pip install webrtcvad-wheels` in your virtual environment, and then retry the Langflow installation.
 
+## 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.
@@ -91,9 +97,140 @@ 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
+### Langflow Installation Error: langflow-install-error
+
+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:
+
+1. Close Langflow Desktop.
+2. Clear Langflow Desktop's Python virtual environment.
+    Navigate to Langflow Desktop's data directory at `%LOCALAPPDATA%\com.LangflowDesktop` on Windows, or `~/Library/Application Support/com.LangflowDesktop` on macOS.
+3. Delete the `venv` or `python_env` folder.
+4. Restart Langflow Desktop.
+
+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 Health Check Error: Timeout after 80 attempts
+
+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:
+
+1. Check if another process is using Langflow Desktop's default port `7860`.
+    * On Windows, run `netstat -ano | findstr :7860`.
+    * On macOS or Linux, run `lsof -i :7860`.
+2. If another process is using the port, stop that process or [configure Langflow Desktop to use a different port](/environment-variables#set-environment-variables-for-langflow-desktop).
+
+### Failed to install uv or unable to find uv
+
+The following error messages mean that Langflow Desktop can't locate the `uv` executable on your system, even though it may be installed:
+
+* `Failed to install uv: Unable to find uv executable`
+* `Unable to find uv executable for Python virtual environment setup`
+* `UV Installation Error: UV installation failed - binary not found after installation`
+* `Python Environment Error: UV binary not found at`
+
+To resolve this error, do the following:
+
+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 `~/.local/bin` to your PATH in `~/.bashrc` or `~/.zshrc`.
+
+   </TabItem>
+   </Tabs>
+
+3. Restart Langflow Desktop.
+
+### Python Environment Error: Creation failed
+
+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:
+
+1. Ensure you have sufficient disk space available (at least 2 GB free).
+2. Ensure that you have write permissions in the Langflow Desktop data directory:
+   * On Windows: `%LOCALAPPDATA%\com.LangflowDesktop`
+   * On macOS: `~/Library/Application Support/com.LangflowDesktop`
+3. Close Langflow Desktop.
+4. Delete the `venv` or `python_env` folder in the Langflow Desktop data directory.
+5. Restart Langflow Desktop.
+
+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).
+
+### Python Environment Error: Python check failed
+
+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.
+
+To resolve this error, see [Python Environment Error: Creation failed](#python-environment-error-creation-failed).
+
+### Langflow Installation Error: error_xcode
+
+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!`.
+
+To resolve this error, do the following:
+
+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.
+
+### 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 `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/).
+
+### 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 error messages like `UV Installation Error: uv-manual-install-required` or a detailed manual installation message.
+
+To resolve this error, do the following:
+
+1. Install `uv` manually using PowerShell:
+    ```powershell
+    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+    ```
+
+    Or install using pip:
+    ```bash
+    pip install uv
+    ```
+
+2. Verify the installation by running `uv --version` in a new PowerShell or Command Prompt window.
+
+   If `uv` is not found, add it to your PATH. In PowerShell, run:
+   ```powershell
+   [System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.cargo\bin", "User")
+   ```
 
-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, follow the on-screen prompt to install Microsoft C++ Build Tools, or [install Microsoft Visual Studio](https://visualstudio.microsoft.com/downloads/).
+3. Restart Langflow Desktop.
 
 ## Langflow startup issues
 
@@ -107,7 +244,7 @@ When you try to run Langflow with the command `langflow run`, you encounter the
 > No module named 'langflow.__main__'
 ```
 
-To resolve this issue, try the following:
+To resolve this issue, do the following:
 
 1. Run `uv run langflow run` instead of `langflow run`.
 2. If that doesn't work, reinstall the latest Langflow version with `uv pip install langflow -U`.