Skip to main content

Troubleshoot Orbis Studio

This page provides troubleshooting advice for issues you might encounter when using Orbis Studio or contributing to Orbis Studio.

Missing components​

As Orbis Studio 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 Core components and menus, try the following:

  • Search for the component.
  • Check other component categories and Bundles.
  • Check legacy components, which are hidden by default.
  • Check the Changelog for component changes in recent releases.
  • Make sure the component isn't already present in your flow if it is a single-use component.

If you still cannot locate the component, see Troubleshoot Orbis Studio.

No input in the Playground​

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.

Missing key, no key found, or invalid API key​

If you get an API key error when running a flow, try the following:

  • For all components that require credentials, make sure those components have a valid credential in the component's settings, such as the API Key field.
  • If you store your credentials in Orbis Studio global variables, make sure you selected the correct global variable and that the variable contains a valid credential.
  • Make sure the provided credentials are active, have the required permissions, and, if applicable, have sufficient funds in the account to execute the required action. For example, model providers require credits to use their LLMs.

Orbis Studio installation issues​

The following issues can occur when installing Orbis Studio.

Orbis Studio installation freezes at pip dependency resolution​

Installing Orbis Studio OSS with pip install langflow slowly fails with this error message:


_10
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 Orbis Studio with uv instead of pip, as explained in Install and run the Orbis Studio OSS Python package.

Linux installation fails to build required package​

When you try to install Orbis Studio OSS on Linux, installation fails because of outdated or missing packages:


_10
Resolved 455 packages in 18.92s
_10
× Failed to build `webrtcvad==2.0.10`
_10
├─▶ The build backend returned an error
_10
╰─▶ 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 Orbis Studio installation:


_10
sudo apt-get update
_10
sudo apt-get install build-essential python3-dev

If upgrading your packages doesn't fix the issue, install gcc separately, and then retry the Orbis Studio installation:


_10
sudo apt-get install gcc

Installation failure from webrtcvad package​

If you experience an error from the webrtcvad package, run uv pip install webrtcvad-wheels in your virtual environment, and then retry the Orbis Studio installation.

Orbis Studio Desktop installation issues​

The following issues can occur when Orbis Studio Desktop installs or updates its bundled Orbis Studio OSS instance.

To view Orbis Studio Desktop logs, see Desktop logs.

Protocol buffers (protoc) required for Intel-based Macs​

If you're installing Orbis Studio 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.

C++ build tools required for Orbis Studio Desktop on Windows​

Microsoft Windows installations of Orbis Studio 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.

Orbis Studio startup issues​

The following issues can occur when attempting to start Orbis Studio.

No langflow.__main__ module​

When you try to run Orbis Studio with the command langflow run, you encounter the following error:


_10
> No module named 'langflow.__main__'

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 Orbis Studio version with uv pip install langflow -U.
  3. If that doesn't work, reinstall Orbis Studio and its dependencies with uv pip install langflow --pre -U --force-reinstall.

Orbis Studio runTraceback​

When you try to run Orbis Studio using the command langflow run, you encounter the following error:


_10
> 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 Orbis Studio installations: You installed Orbis Studio using pip install langflow but you already had a previous version of Orbis Studio 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 Orbis Studio 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 Orbis Studio and its dependencies by running python -m pip install langflow --pre -U --force-reinstall.

Environment variables not available from terminal​

Environment variables set in your terminal aren't automatically available to GUI-based applications like Orbis Studio Desktop when launched through the Finder or the Start Menu. Restart the application from the terminal session where the variables are set, or contact your administrator for help.

Access Orbis Studio Desktop startup logs​

If you encounter issues with Orbis Studio Desktop, you might need to access Orbis Studio Desktop startup logs for debugging.

User not found or inactive when running multiple flows​

When running multiple local Orbis Studio OSS instances on different ports, such as localhost:7860 and localhost:7861, you might see authentication errors in the logs. For example:


_10
[07/22/25 10:57:07] INFO 2025-07-22 10:57:07 - INFO - User not found
_10
[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 Orbis Studio instance.

Package is not installed​

In Orbis Studio OSS, you can follow the error message's instructions to install the missing dependency.

To manage dependencies in Orbis Studio Desktop, see Install custom dependencies in Orbis Studio Desktop.

PostgreSQL asyncpg driver compatibility issue​

The following error can occur when initializing Orbis Studio with a PostgreSQL database:


_10
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 Orbis Studio's current database schema.

To resolve this issue, remove asyncpg from your installation and use psycopg2 instead.

PostgreSQL version mismatch: UNIQUE NULLS DISTINCT syntax error​

The following error can occur when initializing Orbis Studio with a PostgreSQL database. Orbis Studio logs a clear message and then exits:


_10
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:


_10
(psycopg.errors.SyntaxError) syntax error at or near "NULLS"
_10
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 Orbis Studio's database schema. Orbis Studio 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 Orbis Studio.

An API key must be passed as query or header​

The following error can occur when attempting to sign up on the Orbis Studio sign in page: An API key must be passed as query or header.

This means authentication is enforced and only superusers can create and activate non-superuser accounts.

If you aren't an administrator, a superuser must create and activate your account before you can sign in.

If you are the administrator, sign in with your superuser account or contact the Orbislabs team.

For more information, see Start Orbis Studio Server with authentication enabled.

Orbis Studio upgrade issues​

The following issues can occur when upgrading your Orbis Studio version.

For information about managing Orbis Studio versions, see Install Orbis Studio.

There's a mismatch between the models and the database​

The following error can occur during Orbis Studio upgrades when the database schema doesn't match the current version's models:


_10
There's a mismatch between the models and the database.

Back up the database before attempting a migration repair. An administrator can run:


_10
uv run langflow migration --fix

If the migration fix does not resolve the issue, investigate the database schema before clearing any cache. For a disposable local installation, you can clear the Orbis Studio cache folder after backing up your settings. 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.

Orbis Studio Desktop says it is running the latest version, but it is actually behind​

If you are running Orbis Studio Desktop 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 . Earlier versions can't automatically detect or apply updates.

To resolve this issue, uninstall Orbis Studio Desktop, and then download and install the latest version of Orbis Studio Desktop.

422 error when freezing components after upgrading Pydantic/FastAPI dependencies​

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 Orbis Studio installation to or later, which includes a fix for this issue.


_10
uv pip install langflow -U

Orbis Studio uninstall issues​

The following issues can occur when uninstalling Orbis Studio.

Dot directory isn't deleted when uninstalling Orbis Studio Desktop on macOS​

On macOS, uninstalling Orbis Studio Desktop deletes the .app file but doesn't delete files in ~/.langflow, which includes files generated during usage like cache and settings.

If you reinstall Orbis Studio Desktop, it starts with the existing data from the previous installation.

To fully remove an Orbis Studio Desktop macOS installation, you must also delete ~/.langflow:


_10
rm -rf .langflow

Orbis Studio MCP issues​

The following issues can occur when using Orbis Studio as an MCP server or client.

Default project MCP server only works when authentication is None​

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:


_16
{
_16
"mcpServers": {
_16
"PROJECT_NAME": {
_16
"command": "uvx",
_16
"args": [
_16
"mcp-proxy",
_16
"--transport",
_16
"streamablehttp",
_16
"--headers",
_16
"x-api-key",
_16
"YOUR_API_KEY",
_16
"http://LANGFLOW_SERVER_URL/api/v1/mcp/project/PROJECT_ID/streamable"
_16
]
_16
}
_16
}
_16
}

For more information, see Connect clients to your Orbis Studio MCP server.

Claude for Desktop doesn't use MCP server tools correctly​

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:

  1. To find your uvx path, run which uvx.

    To find your npx path, run which npx.

  2. In your claude_desktop_config.json file, add the path to your Orbis Studio MCP server configuration, as shown in the following examples.


    _11
    {
    _11
    "mcpServers": {
    _11
    "PROJECT_NAME": {
    _11
    "command": "PATH_TO_UVX",
    _11
    "args": [
    _11
    "mcp-proxy",
    _11
    "http://LANGFLOW_SERVER_URL/api/v1/mcp/project/PROJECT_ID/streamable"
    _11
    ]
    _11
    }
    _11
    }
    _11
    }

MCP browser-based flows don't open a browser on Windows​

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 Orbis Studio.

For other browser navigation tools, see the provider's documentation for specific troubleshooting guidance.

"No tools or prompts connected" on MCP servers in mixed Windows/WSL environments​

If you encounter "No tools or prompts connected" errors or connection failures when using Orbis Studio Desktop as an MCP server with clients running in different environments, such as Orbis Studio 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 Orbis Studio 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 Orbis Studio Desktop to accept connections from WSL at the default Windows IP address of 10.255.255.254:7860 instead of localhost.

MCP Tools component loses Tool Mode option after upgrading flows​

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 an earlier version of Orbis Studio, do the following:

  1. Select the MCP Tools component in your flow.

  2. Click Code to open the component's code editor.

  3. In the component's template structure, locate the tool_mode field under inputs. The field can be either missing or set to false.

  4. Add the tool_mode field if it's missing, and set it to true:


    _10
    tool_mode = True

  5. Click Check & Save to apply the code changes.

Token length limit errors in Embedding Model components​

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.

Document processing errors in Docker containers​

If you're running Orbis Studio 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 Orbis Studio 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:


_10
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 Orbis Studio Docker image with your own code.

Custom components and integrations issues​

For troubleshooting advice for a third-party integration, see the information about that integration in the Orbis Studio documentation and the provider's documentation.

If you are building a custom component, see Error handling and logging for custom Python components.

Custom components not appearing in the visual editor​

If your custom components are not appearing in the Orbis Studio visual editor, try the following troubleshooting steps:

  1. Ensure your components follow the required directory structure.


    _10
    /your/custom/components/path/
    _10
    └── category_name/ # Required category subfolder that determines menu name
    _10
    ├── __init__.py # Required
    _10
    └── custom_component.py # Component file

  2. Verify each category directory includes an __init__.py file. This is required for Python to recognize the directory as a module.

If you continue to experience issues, contact Orbis Studio support with details about your directory structure and component setup.

Multi-worker deployments​

Workers report JobQueueNotFoundError​

The load balancer is routing poll or stream requests to a different worker than the one that started the build.

To resolve this issue:

  • Ensure ORBISAGENTS_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.
  • Verify all workers can reach the same Redis instance.

For setup instructions, see Deploy Orbis Studio with multiple workers.

Redis connection refused or auth errors​

If your Redis instance requires a password or TLS, you must use ORBISAGENTS_REDIS_QUEUE_URL (for example, rediss://user:password@host:6380/1). The individual ORBISAGENTS_REDIS_QUEUE_HOST and ORBISAGENTS_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.

Cache and queue keys colliding​

If ORBISAGENTS_REDIS_QUEUE_DB is set to the same database index used by the Orbis Studio 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.

Server refuses to start with multiple workers and ORBISAGENTS_JOB_QUEUE_TYPE=asyncio​

Startup 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 ORBISAGENTS_JOB_QUEUE_TYPE=redis on all workers so queue state is shared. This supports all ORBISAGENTS_EVENT_DELIVERY modes.

Builds are cancelled unexpectedly​

The polling watchdog reclaims builds whose client heartbeat has gone stale. The default threshold is 90 seconds (ORBISAGENTS_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.

Intel Mac issues​

The following issues can occur when running Orbis Studio on Intel-based Macs.

"No matching distribution found" errors on Intel Mac​

If you see errors about missing packages after installing Orbis Studio on an Intel Mac, such as:


_10
ERROR: Could not find a version that satisfies the requirement torch
_10
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:


_10
python -c "import platform; print(platform.machine())"
_10
# x86_64 = Intel, arm64 = Apple Silicon

Use core Orbis Studio features or API-based alternatives instead of local ML models.

Performance issues on Intel Mac​

If Orbis Studio feels slow on an Intel Mac:

  1. Ensure you are not trying to run ML workloads locally, as these are not supported on Intel Macs.
  2. Use API-based providers for embeddings and completions instead of local models.
  3. Consider upgrading to Apple Silicon for better performance with ML features.

See also​