diff --git a/docs/docs/Support/troubleshooting.mdx b/docs/docs/Support/troubleshooting.mdx index 620ddda9db4c..f33cce829e71 100644 --- a/docs/docs/Support/troubleshooting.mdx +++ b/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,134 @@ 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 failed + +Langflow Desktop installed Langflow OSS but couldn't verify the installation. You might see an error dialog with the title `Langflow Installation Failed` and the message `Langflow installation failed. Please check your internet connection and try again. If the problem persists, restart the application.` + +To resolve this error, clear Langflow Desktop's Python virtual environment: + +1. Close Langflow Desktop. +2. 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 startup failed + +Langflow Desktop installed Langflow OSS but the OSS backend isn't responding to health checks. You might see an error dialog with the title `Langflow Startup Failed` and the message `Langflow failed to start properly. Please restart the application and try again.` + +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 + +Langflow Desktop can't locate or install the `uv` executable. You might see an error dialog with the title `UV Installation Failed` and the message `UV installation failed. Please check your internet connection and try again. If the problem persists, restart the application.` + +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: + + + + + 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 + ``` + + + + + 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`. + + + + +3. Restart Langflow Desktop. + +### Python environment failed + +Langflow Desktop failed to create the Python virtual environment required for Langflow OSS. You might see an error dialog with the title `Python Environment Failed` and the message `Python environment setup failed. Please ensure you have sufficient disk space and try again.` + +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 or later is installed and accessible, or reinstall Langflow Desktop from [langflow.org/desktop](https://langflow.org/desktop). + +### Python environment failed: Python check failed -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/). +Langflow Desktop created the Python virtual environment but couldn't verify that Python is working correctly. You might see an error dialog with the title `Python Environment Failed` and a message about Python verification. + +To resolve this error, see [Python environment failed](#python-environment-failed). + +### Xcode Command Line Tools required + +Langflow Desktop requires [Xcode Command Line Tools](https://developer.apple.com/xcode/resources/) to install Langflow OSS on macOS. You might see an error dialog with the title `Xcode Command Line Tools required!` and instructions to run `xcode-select --install`. + +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. + +### C++ build tools required + +Microsoft Windows installations of Langflow Desktop require a C++ compiler that might not be present on your system. +You might see an error dialog with the title `C++ Build Tools required!` with instructions to install Microsoft C++ Build Tools. Follow the on-screen prompt, or install [Microsoft Visual Studio](https://visualstudio.microsoft.com/downloads/). + +### Manual UV installation 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 might see an error dialog with the title `Manual UV Installation Required` and instructions to install `uv` manually. + +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") + ``` + +3. Restart Langflow Desktop. ## Langflow startup issues @@ -107,7 +238,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`. @@ -146,7 +277,8 @@ When running multiple local Langflow OSS instances on different ports, such as ` For example: ```text -[07/22/25 10:57:07] INFO 2025-07-22 10:57:07 - INFO - utils - User not found or inactive. +[07/22/25 10:57:07] INFO 2025-07-22 10:57:07 - INFO - User not found +[07/22/25 10:57:07] INFO 2025-07-22 10:57:07 - INFO - User is inactive ``` To resolve this error, use separate browser instances or browser profiles to access each Langflow instance. @@ -171,7 +303,14 @@ To resolve this issue, remove `asyncpg` from your installation and use `psycopg2 ### PostgreSQL version mismatch: `UNIQUE NULLS DISTINCT` syntax error -The following error can occur when initializing Langflow with a PostgreSQL database: +The following error can occur when initializing Langflow with a PostgreSQL database. +Langflow logs a clear message and then exits: + +```text +Langflow requires PostgreSQL 15 or higher when using PostgreSQL as the database. The current PostgreSQL version does not support the syntax used by Langflow's schema. Please upgrade your PostgreSQL instance to version 15 or higher. +``` + +You may also see the underlying SQL error in the traceback: ```text (psycopg.errors.SyntaxError) syntax error at or near "NULLS" @@ -203,15 +342,21 @@ The following issues can occur when upgrading your Langflow version. For information about managing Langflow versions, see [Install Langflow](/get-started-installation). -### Something went wrong running migrations +### There's a mismatch between the models and the database + +The following error can occur during Langflow upgrades when the database schema doesn't match the current version's models: + +```bash +There's a mismatch between the models and the database. +``` -The following error can occur during Langflow upgrades when the new version can't override `langflow-pre.db` in the Langflow cache folder: +To resolve this error, run the migration fix command: ```bash -> Something went wrong running migrations. Please, run 'langflow migration --fix' +uv run langflow migration --fix ``` -To resolve this error, clear the cache by deleting the contents of your Langflow cache folder. +If the migration fix doesn't resolve the issue, clear the cache by deleting the contents of your Langflow cache folder. The filepath depends on your operating system, installation type, and configuration options. For more information and default filepaths, see [Memory management options](/memory).