Skip to main content

Troubleshoot SkillFlaw

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

Missing components​

As SkillFlaw 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 SkillFlaw GitHub Issues and Discussions.

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

SkillFlaw installation issues​

The following issues can occur when installing SkillFlaw.

Repository installation freezes at dependency resolution​

Installing repository dependencies with ad-hoc Python package commands can slowly fail 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, use the repository-managed uv workflow described in Install SkillFlaw from source.

Linux installation fails to build required package​

When you try to install SkillFlaw 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 SkillFlaw 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 SkillFlaw 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 SkillFlaw installation.

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

If you're installing SkillFlaw 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 SkillFlaw Desktop on Windows​

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

SkillFlaw startup issues​

The following issues can occur when attempting to start SkillFlaw.

No skillflaw.__main__ module​

When you try to run SkillFlaw with the command skillflaw run, you encounter the following error:


_10
> No module named 'skillflaw.__main__'

To resolve this issue, try the following:

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

SkillFlaw runTraceback​

When you try to run SkillFlaw using the command skillflaw run, you encounter the following error:


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

There are two possible reasons for this error:

  • Multiple SkillFlaw installations: You installed SkillFlaw using pip install skillflaw but you already had a previous version of SkillFlaw 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 skillflaw run instead of skillflaw run.

    If that doesn't work, try uninstalling and reinstalling SkillFlaw with uv pip install skillflaw --pre -U.

  • Version conflict during installation: Some version conflicts might have occurred during the installation process. To resolve this issue, reinstall SkillFlaw and its dependencies by running python -m pip install skillflaw --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 SkillFlaw Desktop when launched through the Finder or the Start Menu. To set environment variables for SkillFlaw Desktop, see Set environment variables for SkillFlaw Desktop.

Access SkillFlaw Desktop startup logs​

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

User not found or inactive when running multiple flows​

When running multiple local SkillFlaw 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 - utils - User not found or inactive.

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

Package is not installed​

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

To manage dependencies in SkillFlaw Desktop, see Install custom dependencies in SkillFlaw Desktop.

PostgreSQL asyncpg driver compatibility issue​

The following error can occur when initializing SkillFlaw 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 SkillFlaw's current database schema.

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

An API key must be passed as query or header​

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

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

For more information, see Configure a secured SkillFlaw server.

SkillFlaw upgrade issues​

The following issues can occur when upgrading your SkillFlaw version.

For information about managing SkillFlaw versions, see Install SkillFlaw.

Something went wrong running migrations​

The following error can occur during SkillFlaw upgrades when the new version can't override skillflaw-pre.db in the SkillFlaw cache folder:


_10
> Something went wrong running migrations. Please, run 'skillflaw migration --fix'

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

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

If you are running SkillFlaw 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 SkillFlaw Desktop, and then download and install the latest desktop version from the current SkillFlaw distribution channel used by your organization or deployment workflow.

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


_10
uv pip install skillflaw -U

SkillFlaw uninstall issues​

The following issues can occur when uninstalling SkillFlaw.

Cache directory isn't deleted when uninstalling SkillFlaw Desktop on macOS​

On macOS, uninstalling SkillFlaw Desktop deletes the .app file but doesn't delete files in SkillFlaw's cache directory, which by default is ~/Library/Caches/skillflaw and includes files generated during usage like cache and settings.

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

To fully remove a SkillFlaw Desktop macOS installation, you must also delete ~/Library/Caches/skillflaw or the custom cache path that you configured:


_10
rm -rf ~/Library/Caches/skillflaw

SkillFlaw MCP issues​

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

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 SkillFlaw 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://SKILLFLAW_SERVER_ADDRESS/api/v1/mcp/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 SkillFlaw.

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 SkillFlaw Desktop as an MCP server with clients running in different environments, such as SkillFlaw 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 SkillFlaw 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 SkillFlaw 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 SkillFlaw version 1.7.1 or earlier, 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 containerized environments​

If you're using a Docling-based document processing workflow in a Linux-based containerized environment, you might encounter errors if the runtime that performs Docling conversion is missing required system libraries.

In current SkillFlaw releases, this usually applies to your self-managed Docling components runtime, such as a separate Docling Serve deployment, rather than the standard Read File component.

When the Docling runtime runs in a minimal Linux container, it may require system libraries that aren't installed by default. If you see errors related to document or image processing, install the following packages in the container or host that runs Docling conversion:


_10
apt-get update && apt-get install -y libgl1 libglib2.0-0

These dependencies are required by Docling for document processing operations. If SkillFlaw connects to Docling through Docling Serve, install them on the Docling Serve side and then restart that service.

Custom components and integrations issues​

For troubleshooting advice for a third-party integration, see the information about that integration in the SkillFlaw 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 SkillFlaw visual editor, try the following troubleshooting steps:

  1. Ensure your components follow the required directory structure.


    _10
    /your/custom/components/path/ # Base directory set by SKILLFLAW_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.

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


    _10
    uv run skillflaw 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.

See also​