flow/docs/versioned_docs/version-1.8.0/Support/troubleshooting.mdx

---
title: Troubleshoot Hanzo Flow
slug: /troubleshoot
---

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 Hanzo Flow or contributing to Hanzo Flow.

## Missing components

As Hanzo Flow 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:

* <Icon name="Search" aria-hidden="true" /> **Search** for the component.
* Check other component categories and <Icon name="Blocks" aria-hidden="true" /> [**Bundles**](/components-bundle-components).
* Check [legacy components](/concepts-components#legacy-components), which are hidden by default.
* Check the [Changelog](https://github.com/hanzoai/flow/releases/latest) 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 [Hanzo Flow GitHub Issues and Discussions](/contributing-github-issues).

## No input in the Playground

If there is no message input field in the **Playground**, make sure your flow has a [**Chat Input** component](/chat-input-and-output) 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](/concepts-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 [Hanzo Flow global variables](/configuration-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.

## Hanzo Flow installation issues

The following issues can occur when installing Hanzo Flow.

### Hanzo Flow installation freezes at pip dependency resolution

Installing Hanzo Flow OSS with `pip install flow` slowly fails with this error message:

```text
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 Hanzo Flow with `uv` instead of `pip`, as explained in [Install and run the Hanzo Flow OSS Python package](/get-started-installation#install-and-run-the-flow-oss-python-package).

### Linux installation fails to build required package

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

```bash
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 Hanzo Flow installation:

```bash
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 Hanzo Flow installation:

```bash
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 Hanzo Flow installation.

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

If you're installing Hanzo Flow 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](https://protobuf.dev/installation/).

### C++ build tools required for Hanzo Flow Desktop on Windows

Microsoft Windows installations of Hanzo Flow 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/).

## Hanzo Flow startup issues

The following issues can occur when attempting to start Hanzo Flow.

### No `flow.__main__` module

When you try to run Hanzo Flow with the command `flow run`, you encounter the following error:

```bash
> No module named 'flow.__main__'
```

To resolve this issue, try the following:

1. Run `uv run flow run` instead of `flow run`.
2. If that doesn't work, reinstall the latest Hanzo Flow version with `uv pip install flow -U`.
3. If that doesn't work, reinstall Hanzo Flow and its dependencies with `uv pip install flow --pre -U --force-reinstall`.

### Hanzo Flow runTraceback

When you try to run Hanzo Flow using the command `flow run`, you encounter the following error:

```bash
> flow runTraceback (most recent call last): File ".../flow", line 5, in <module>  from flow.__main__ import mainModuleNotFoundError: No module named 'flow.__main__'
```

There are two possible reasons for this error:

* **Multiple Hanzo Flow installations**: You installed Hanzo Flow using `pip install flow` but you already had a previous version of Hanzo Flow 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 flow run` instead of `flow run`.

    If that doesn't work, try uninstalling and reinstalling Hanzo Flow with `uv pip install flow --pre -U`.

* **Version conflict during installation**: Some version conflicts might have occurred during the installation process. To resolve this issue, reinstall Hanzo Flow and its dependencies by running `python -m pip install flow --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 Hanzo Flow Desktop when launched through the Finder or the Start Menu.
To set environment variables for Hanzo Flow Desktop, see [Set environment variables for Hanzo Flow Desktop](/environment-variables#set-environment-variables-for-flow-desktop).

### Access Hanzo Flow Desktop startup logs

If you encounter issues with Hanzo Flow Desktop, you might need to [access Hanzo Flow Desktop startup logs](/logging#desktop-logs) for debugging.

### User not found or inactive when running multiple flows

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

```text
[07/22/25 10:57:07] INFO     2025-07-22 10:57:07 - INFO     - utils - User not found or inactive.
```

To resolve this error, use separate browser instances or browser profiles to access each Hanzo Flow instance.

### Package is not installed

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

To manage dependencies in Hanzo Flow Desktop, see [Install custom dependencies in Hanzo Flow Desktop](/install-custom-dependencies#flow-desktop).

### PostgreSQL asyncpg driver compatibility issue

The following error can occur when initializing Hanzo Flow with a PostgreSQL database:

```text
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 Hanzo Flow'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 Hanzo Flow with a PostgreSQL database:

```text
(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 Hanzo Flow's database schema.
Hanzo Flow 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 Hanzo Flow.

### An API key must be passed as query or header

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

This means that `FLOW_AUTO_LOGIN` is set to `false`, and only superusers can create and activate non-superuser accounts.
Therefore, you are locked out of this Hanzo Flow 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 Hanzo Flow with `FLOW_AUTO_LOGIN=true`.

For more information, see [Start Hanzo Flow Server with authentication enabled](/api-keys-and-authentication#start-a-flow-server-with-authentication-enabled).

## Hanzo Flow upgrade issues

The following issues can occur when upgrading your Hanzo Flow version.

For information about managing Hanzo Flow versions, see [Install Hanzo Flow](/get-started-installation).

### Something went wrong running migrations

The following error can occur during Hanzo Flow upgrades when the new version can't override `flow-pre.db` in the Hanzo Flow cache folder:

```bash
> Something went wrong running migrations. Please, run 'flow migration --fix'
```

To resolve this error, clear the cache by deleting the contents of your Hanzo Flow 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).

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

### Hanzo Flow Desktop says it is running the latest version, but it is actually behind

If you are running Hanzo Flow 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 Hanzo Flow Desktop, and then [download and install the latest version of Hanzo Flow Desktop](https://flow.org/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 Hanzo Flow installation to version 1.6.5 or later, which includes a fix for this issue.

```bash
uv pip install flow -U
```

## Hanzo Flow uninstall issues

The following issues can occur when uninstalling Hanzo Flow.

### Dot directory isn't deleted when uninstalling Hanzo Flow Desktop on macOS

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

If you reinstall Hanzo Flow Desktop, it starts with the existing data from the previous installation.

To fully remove a Hanzo Flow Desktop macOS installation, you must also delete `~/.flow`:

    ```bash
    rm -rf .flow
    ```

## Hanzo Flow MCP issues {#mcp}

The following issues can occur when using Hanzo Flow 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:

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

For more information, see [Connect clients to your Hanzo Flow MCP server](/mcp-server#connect-clients-to-use-the-servers-actions).

### 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 Hanzo Flow MCP server configuration, as shown in the following examples.

    <Tabs>
    <TabItem value="uvx" label="uvx" default>

    ```json
    {
      "mcpServers": {
        "PROJECT_NAME": {
          "command": "PATH_TO_UVX",
          "args": [
            "mcp-proxy",
            "http://FLOW_SERVER_ADDRESS/v1/mcp/project/PROJECT_ID/streamable"
          ]
        }
      }
    }
    ```

    </TabItem>
    <TabItem value="npx" label="npx">

    ```json
    {
      "mcpServers": {
        "PROJECT_NAME": {
          "command": "PATH_TO_NPX",
          "args": [
            "-y",
            "supergateway",
            "--sse",
            "http://FLOW_SERVER_ADDRESS/v1/mcp/project/PROJECT_ID/streamable"
          ]
        }
      }
    }
    ```

    </TabItem>
    </Tabs>

### 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](https://github.com/microsoft/playwright-mcp?tab=readme-ov-file#standalone-mcp-server).
After the server is up and running, you can add it as an HTTP/SSE server in Hanzo Flow.

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 Hanzo Flow Desktop as an MCP server with clients running in different environments, such as Hanzo Flow 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 Hanzo Flow 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 Hanzo Flow 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 {#mcp-tools-component-loses-tool-mode-option-after-upgrading-flows}

If you upgrade an existing flow that uses the [**MCP Tools** component](/mcp-tools) 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 Hanzo Flow version 1.7.1 or earlier, do the following:

1. Select the **MCP Tools** component in your flow.
2. Click <Icon name="Code" aria-hidden="true"/> **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`:

   ```python
   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](/split-text#chunk-size).

## Document processing errors in Docker containers

If you're running Hanzo Flow in a Docker container, you might encounter errors when using components that handle files or images, such as the [**Read File** component](/read-file) or [**Docling** components](/bundles-docling). To resolve these errors, you might need to install additional system dependencies.

When running Hanzo Flow 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:

```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 Hanzo Flow Docker image with your own code](/deployment-docker#customize-the-flow-docker-image).

## Custom components and integrations issues

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

If you are building a custom component, see [Error handling and logging for custom Python components](/components-custom-components#error-handling-and-logging).

### Custom components not appearing in the visual editor

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

1. Ensure your components follow the [required directory structure](https://docs.flow.org/components-custom-components#directory-structure-requirements).
    ```
    /your/custom/components/path/       # Base directory set by FLOW_COMPONENTS_PATH
        └── category_name/              # Required category subfolder that determines menu name
            ├── __init__.py             # Required
            └── 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.

3. Use the command line argument instead of the environment variable for `FLOW_COMPONENTS_PATH`.
If you're using the `FLOW_COMPONENTS_PATH` environment variable and components aren't loading, try the `--components-path` command line argument instead:

    ```bash
    uv run flow run --components-path /path/to/your/custom/components
    ```

If you continue to experience issues, please [report them on GitHub](https://github.com/hanzoai/flow/issues) with details about your directory structure and component setup.

## See also

- [Hanzo Flow GitHub Issues and Discussions](/contributing-github-issues)
- [Hanzo Flow telemetry](/contributing-telemetry)