docs/versioned_docs/version-1.10.0/Support/troubleshooting.mdx
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Icon from "@site/src/components/icon";
This page provides troubleshooting advice for issues you might encounter when using Langflow or contributing to Langflow.
As Langflow development continues, components are often recategorized or deprecated for better alignment or to prepare for new components.
If a component appears to be missing from the <Icon name="Component" aria-hidden="true" /> Core components and menus, try the following:
If you still cannot locate the component, see Langflow GitHub Issues and Discussions.
If there is no message input field in the Playground, make sure your flow has a Chat Input component that is connected, directly or indirectly, to the Input port of a Language Model or Agent component.
Because the Playground is designed for flows that use an LLM in a query-and-response format, such as chatbots and agents, a flow must have Chat Input, Language Model/Agent, and Chat Output components to be fully supported by the Playground chat interface.
For more information, see Test flows in the Playground.
If you get an API key error when running a flow, try the following:
The following issues can occur when installing Langflow.
Installing Langflow OSS with pip install langflow slowly fails with this error message:
pip is looking at multiple versions of <<library>> to determine which version is compatible with other requirements. This could take a while.
To work around this issue, install Langflow with uv instead of pip, as explained in Install and run the Langflow OSS Python package.
When you try to install Langflow OSS on Linux, installation fails because of outdated or missing packages:
Resolved 455 packages in 18.92s
× Failed to build `webrtcvad==2.0.10`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
To resolve this error, install the required build dependencies, and then retry the Langflow installation:
sudo apt-get update
sudo apt-get install build-essential python3-dev
If upgrading your packages doesn't fix the issue, install gcc separately, and then retry the Langflow installation:
sudo apt-get install gcc
webrtcvad packageIf you experience an error from the webrtcvad package, run uv pip install webrtcvad-wheels in your virtual environment, and then retry the Langflow installation.
The following issues can occur when Langflow Desktop installs or updates its bundled Langflow OSS instance.
To view Langflow Desktop logs, see Desktop logs.
If you're installing Langflow on an Intel-based Mac, you may encounter installation errors if Protocol Buffers Compiler (protoc) is not installed.
This requirement doesn't apply to Apple Silicon Macs on ARM64.
To resolve this issue, install protoc using brew install protobuf.
For more information, including alternative installation methods, see the Protocol buffers installation documentation.
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:
%LOCALAPPDATA%\com.LangflowDesktop on Windows, or ~/Library/Application Support/com.LangflowDesktop on macOS.venv or python_env folder.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.
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:
7860.
netstat -ano | findstr :7860.lsof -i :7860.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:
In a terminal verify uv is installed by running uv --version.
Based on the output, install uv or add it to your PATH:
Install uv using one of the following methods:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
curl -LsSf https://astral.sh/uv/install.sh | sh
pip install uv
Add uv to your PATH so Langflow Desktop can locate it:
[System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.cargo\bin", "User")
~/.local/bin to your PATH in ~/.bashrc or ~/.zshrc.Restart Langflow Desktop.
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:
%LOCALAPPDATA%\com.LangflowDesktop~/Library/Application Support/com.LangflowDesktopvenv or python_env folder in the Langflow Desktop data directory.If the issue persists, ensure Python version 3.10 or later is installed and accessible, or reinstall Langflow Desktop from langflow.org/desktop.
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.
Langflow Desktop requires Xcode Command Line Tools 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:
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.
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:
Install uv manually using PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Or install using pip:
pip install uv
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:
[System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.cargo\bin", "User")
Restart Langflow Desktop.
Uninstalling Langflow depends on how it was installed, and on which operating system.
If you reinstall Langflow after uninstalling, any data you didn't delete will be picked up automatically by the new installation. Delete the data directories listed below if you want a completely fresh start.
To uninstall the Langflow OSS Python package, run the following command in the virtual environment where Langflow is installed:
uv pip uninstall langflow
To remove the Langflow data directory, which contains your flows, settings, and cache, run:
<Tabs> <TabItem value="mac-linux" label="macOS / Linux" default>rm -rf ~/.langflow
Remove-Item -Recurse -Force "$env:USERPROFILE\.langflow"
To uninstall Langflow Desktop, uninstall the application with your OS package manager, and then manually delete the remaining data directories.
<Tabs> <TabItem value="macos" label="macOS" default>Drag Langflow.app from /Applications to the Trash, or right-click and select Move to Trash.
Empty the Trash to remove the application file.
To remove the Langflow data directory, run the following command:
rm -rf ~/.langflow
To remove the Desktop app support files, run the following commands:
rm -rf ~/Library/Application\ Support/com.LangflowDesktop
rm -rf ~/Library/Caches/com.LangflowDesktop
rm -rf ~/Library/Logs/com.LangflowDesktop
rm -f ~/Library/Preferences/com.LangflowDesktop.plist
rm -rf ~/Library/WebKit/com.LangflowDesktop
Open Settings > Apps > Installed apps.
Find Langflow in the list, click the menu (...), and select Uninstall.
Follow the on-screen prompts to complete the uninstallation.
To remove the Langflow data directory, run the following command:
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\com.LangflowDesktop"
The following issues can occur when attempting to start Langflow.
langflow.__main__ moduleWhen you try to run Langflow with the command langflow run, you encounter the following error:
> No module named 'langflow.__main__'
To resolve this issue, do the following:
uv run langflow run instead of langflow run.uv pip install langflow -U.uv pip install langflow --pre -U --force-reinstall.When you try to run Langflow using the command langflow run, you encounter the following error:
> langflow runTraceback (most recent call last): File ".../langflow", line 5, in <module> from langflow.__main__ import mainModuleNotFoundError: No module named 'langflow.__main__'
There are two possible reasons for this error:
Multiple Langflow installations: You installed Langflow using pip install langflow but you already had a previous version of Langflow installed in your system. In this case, you might be running the wrong executable.
To solve this issue, run the correct executable by running python -m langflow run instead of langflow run.
If that doesn't work, try uninstalling and reinstalling Langflow with uv pip install langflow --pre -U.
Version conflict during installation: Some version conflicts might have occurred during the installation process. To resolve this issue, reinstall Langflow and its dependencies by running python -m pip install langflow --pre -U --force-reinstall.
Environment variables set in your terminal aren't automatically available to GUI-based applications like Langflow Desktop when launched through the Finder or the Start Menu. To set environment variables for Langflow Desktop, see Set environment variables for Langflow Desktop.
If you encounter issues with Langflow Desktop, you might need to access Langflow Desktop startup logs for debugging.
When running multiple local Langflow OSS instances on different ports, such as localhost:7860 and localhost:7861, you might see authentication errors in the logs.
For example:
[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.
In Langflow OSS, you can follow the error message's instructions to install the missing dependency.
To manage dependencies in Langflow Desktop, see Install custom dependencies in Langflow Desktop.
The following error can occur when initializing Langflow with a PostgreSQL database:
sqlalchemy.exc.DBAPIError: (sqlalchemy.dialects.postgresql.asyncpg.Error) <class 'asyncpg.exceptions.DataError'>: invalid input for query argument $7: datetime.datetime(2025, 10, 31, 14, 8, 5... (can't subtract offset-naive and offset-aware datetimes)
This error occurs because asyncpg has stricter timezone handling than psycopg2, and is not fully compatible with Langflow's current database schema.
To resolve this issue, remove asyncpg from your installation and use psycopg2 instead.
UNIQUE NULLS DISTINCT syntax errorThe following error can occur when initializing Langflow with a PostgreSQL database. Langflow logs a clear message and then exits:
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:
(psycopg.errors.SyntaxError) syntax error at or near "NULLS"
LINE 13: CONSTRAINT file_name_user_id_key UNIQUE NULLS DISTINCT (nam...
This occurs when you're using a PostgreSQL version prior to version 15.
These versions don't support the UNIQUE NULLS DISTINCT syntax used by Langflow's database schema.
Langflow requires PostgreSQL 15 or higher when configured to use PostgreSQL.
To resolve this issue, upgrade your PostgreSQL instance to version 15 or higher, and then restart Langflow.
The following error can occur when attempting to sign up on the Langflow sign in page: An API key must be passed as query or header.
This means that LANGFLOW_AUTO_LOGIN is set to false, and only superusers can create and activate non-superuser accounts.
Therefore, you are locked out of this Langflow instance.
If you aren't an administrator, then a superuser must create and activate a non-superuser account before you can sign in.
If you are the administrator, sign in with a superuser account, or restart Langflow with LANGFLOW_AUTO_LOGIN=true.
For more information, see Start Langflow Server with authentication enabled.
/app/langflow/secret_key at startupThe Langflow container runs as a non-root user (uid=1000).
The Langflow image pre-creates /app/langflow with that user as the owner, so a new langflow-data named volume inherits the correct ownership.
If you ran an earlier image build that did not pre-create this directory, the named volume was initialized as root:root and the non-root container user cannot write secret_key into it, and the error PermissionError: [Errno 13] on /app/langflow/secret_key appears.
This commonly affects rootful Docker daemons such as Docker Desktop. Podman with rootless user-namespace mapping does not reproduce the issue.
To preserve the langflow-postgres data while resetting only the langflow-data volume, do the following:
Stop the container and find the exact volume name for langflow-data.
This command lists the volumes, and then searches for langflow-data.
docker compose down
docker compose config --volumes
docker volume ls | grep langflow-data
Once you have confirmed the exact volume name, remove only that volume:
docker volume rm LANGFLOW_DATA_VOLUME_NAME
docker compose pull
docker compose up -d
Alternatively, if you don't need to preserve the langflow-postgres data volume, you can pull the latest container image instead.
:::danger
This method removes all data, including the langflow-postgres data volume.
:::
docker compose down -v
docker compose pull
docker compose up -d
The following issues can occur when upgrading your Langflow version.
For information about managing Langflow versions, see Install Langflow.
The following error can occur during Langflow upgrades when the database schema doesn't match the current version's models:
There's a mismatch between the models and the database.
To resolve this error, run the migration fix command:
uv run langflow migration --fix
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.
:::danger Clearing the cache erases your settings. If you want to retain your settings files, create a backup of those files before clearing the cache folder. :::
If you are running Langflow Desktop version 1.4.2 or earlier, the UI might incorrectly report that you are on the latest version when a newer version is available.
This happens because the automatic update feature in the UI was introduced in version 1.4.2. Earlier versions can't automatically detect or apply updates.
To resolve this issue, uninstall Langflow Desktop, and then download and install the latest version of Langflow Desktop.
If you locally upgrade your Pydantic and FastAPI dependencies, you may encounter a 422 error when trying to freeze components.
This error occurs due to changes in how request bodies are handled in newer versions of these dependencies.
If you're experiencing this issue, update your Langflow installation to version 1.6.5 or later, which includes a fix for this issue.
uv pip install langflow -U
The following issues can occur when using Langflow as an MCP server or client.
If the default project MCP server works without authentication, but fails after adding an API key to the server configuration, the API key might have been added to the wrong section of the configuration.
The default MCP server uses streamable HTTP transport.
The API key must be added to the args array that is passed to mcp-proxy, not the env object.
Your args array must include "--headers", "x-api-key", and your key value. For example:
{
"mcpServers": {
"PROJECT_NAME": {
"command": "uvx",
"args": [
"mcp-proxy",
"--transport",
"streamablehttp",
"--headers",
"x-api-key",
"YOUR_API_KEY",
"http://LANGFLOW_SERVER_ADDRESS/api/v1/mcp/project/PROJECT_ID/streamable"
]
}
}
}
For more information, see Connect clients to your Langflow MCP server.
If Claude for Desktop doesn't use your server's tools correctly, try explicitly defining the path to your local uvx or npx executable file in the claude_desktop_config.json configuration file:
To find your uvx path, run which uvx.
To find your npx path, run which npx.
In your claude_desktop_config.json file, add the path to your Langflow MCP server configuration, as shown in the following examples.
{
"mcpServers": {
"PROJECT_NAME": {
"command": "PATH_TO_UVX",
"args": [
"mcp-proxy",
"http://LANGFLOW_SERVER_ADDRESS/api/v1/mcp/project/PROJECT_ID/streamable"
]
}
}
}
{
"mcpServers": {
"PROJECT_NAME": {
"command": "PATH_TO_NPX",
"args": [
"-y",
"supergateway",
"--sse",
"http://LANGFLOW_SERVER_ADDRESS/api/v1/mcp/project/PROJECT_ID/streamable"
]
}
}
}
This is a known issue when using MCP Tools with browser navigation actions, such as Playwright, on Windows: The agent can execute the tool successfully but the browser tab or window doesn't open.
This issue occurs because the MCP server runs from a Python process, which prevents it from opening browser windows in WSL or Windows.
To work around this issue, use the standalone MCP server approach documented in the Playwright MCP repository. After the server is up and running, you can add it as an HTTP/SSE server in Langflow.
For other browser navigation tools, see the provider's documentation for specific troubleshooting guidance.
If you encounter "No tools or prompts connected" errors or connection failures when using Langflow Desktop as an MCP server with clients running in different environments, such as Langflow on a Windows host and an MCP client in WSL, this is due to network isolation between Windows and WSL environments.
WSL cannot directly access Windows localhost services, and Langflow running on a Windows host is not accessible from WSL clients at localhost:7860.
To work around this issue, run the server and host in the same operating environment.
Alternatively, configure Langflow Desktop to accept connections from WSL at the default Windows IP address of 10.255.255.254:7860 instead of localhost.
If you upgrade an existing flow that uses the MCP Tools component in Tool Mode, the component might lose its Tool Mode setting after upgrading the flow. This can break flows that rely on the component's Tool Mode to expose MCP tools to agents.
If you experience this when upgrading a flow that you created in Langflow version 1.7.1 or earlier, do the following:
Select the MCP Tools component in your flow.
Click <Icon name="Code" aria-hidden="true"/> Code to open the component's code editor.
In the component's template structure, locate the tool_mode field under inputs.
The field can be either missing or set to false.
Add the tool_mode field if it's missing, and set it to true:
tool_mode = True
Click Check & Save to apply the code changes.
Token length errors can happen if your chunking strategy doesn't align with your embedding model's tokenization limits. For more information, see Tokenization errors due to chunk size.
If you're running Langflow in a Docker container, you might encounter errors when using components that handle files or images, such as the Read File component or Docling components. To resolve these errors, you might need to install additional system dependencies.
When running Langflow in a Linux-based Docker container, Docling requires system libraries that aren't included in the base Docker image. If you see errors related to document or image processing, add the following to your Dockerfile:
RUN apt-get update && apt-get install -y libgl1 libglib2.0-0
These dependencies are required by Docling for document processing operations.
For more information about customizing Docker images, see Customize the Langflow Docker image with your own code.
For troubleshooting advice for a third-party integration, see the information about that integration in the Langflow documentation and the provider's documentation.
If you are building a custom component, see Error handling and logging for custom Python components.
If your custom components are not appearing in the Langflow visual editor, try the following troubleshooting steps:
Ensure your components follow the required directory structure.
/your/custom/components/path/ # Base directory set by LANGFLOW_COMPONENTS_PATH
└── category_name/ # Required category subfolder that determines menu name
├── __init__.py # Required
└── custom_component.py # Component file
Verify each category directory includes an __init__.py file.
This is required for Python to recognize the directory as a module.
Use the command line argument instead of the environment variable for LANGFLOW_COMPONENTS_PATH.
If you're using the LANGFLOW_COMPONENTS_PATH environment variable and components aren't loading, try the --components-path command line argument instead:
uv run langflow run --components-path /path/to/your/custom/components
If you continue to experience issues, please report them on GitHub with details about your directory structure and component setup.
JobQueueNotFoundErrorThe load balancer is routing poll or stream requests to a different worker than the one that started the build.
To resolve this issue:
LANGFLOW_JOB_QUEUE_TYPE=redis is set on all workers, not just some. Mixed-mode deployments (some workers using asyncio, others using redis) are not supported.For setup instructions, see Deploy Langflow with multiple workers.
If your Redis instance requires a password or TLS, you must use LANGFLOW_REDIS_QUEUE_URL (for example, rediss://user:password@host:6380/1). The individual LANGFLOW_REDIS_QUEUE_HOST and LANGFLOW_REDIS_QUEUE_PORT settings construct a plain unauthenticated connection and do not support auth or TLS. Managed Redis services such as AWS ElastiCache with AUTH, Google MemoryStore with TLS, and Upstash all require the URL form.
If LANGFLOW_REDIS_QUEUE_DB is set to the same database index used by the Langflow cache, keys from both systems will mix and produce unpredictable behavior.
The cache defaults to DB 0 and the job queue defaults to DB 1. Verify both settings point to different database indices.
LANGFLOW_JOB_QUEUE_TYPE=asyncioStartup fails with a RuntimeError that explains the in-memory job queue is worker-local.
Polling and streaming delivery use a follow-up GET /api/v1/build/<job_id>/events request after the initial build POST, and the load balancer can route those requests to different workers, which produces intermittent "Job not found" errors.
Set LANGFLOW_JOB_QUEUE_TYPE=redis on all workers so queue state is shared. This supports all LANGFLOW_EVENT_DELIVERY modes.
The polling watchdog reclaims builds whose client heartbeat has gone stale. The default threshold is 90 seconds (LANGFLOW_REDIS_QUEUE_POLLING_STALE_THRESHOLD_S=90). If legitimate long-running builds are being cancelled, increase this value or set it to 0 to disable the watchdog entirely.
The following issues can occur when running Langflow on Intel-based Macs.
If you see errors about missing packages after installing Langflow on an Intel Mac, such as:
ERROR: Could not find a version that satisfies the requirement torch
ERROR: No matching distribution found for torch
This is expected behavior. ML packages such as PyTorch are intentionally excluded on Intel Macs because PyTorch dropped support for macOS x86_64 starting with version 2.3.0.
To verify your architecture and understand which features are available, run:
python -c "import platform; print(platform.machine())"
# x86_64 = Intel, arm64 = Apple Silicon
Use core Langflow features or API-based alternatives instead of local ML models. For details on which features are available and workarounds, see macOS support.
If Langflow feels slow on an Intel Mac:
For more information, see Workarounds for Intel Mac users.