From 5099ffcab88d730bb74c58299f0dd803ef0c858e Mon Sep 17 00:00:00 2001
From: Mendon Kissling <59585235+mendonk@users.noreply.github.com>
Date: Thu, 21 Aug 2025 12:41:39 -0400
Subject: [PATCH] docs: custom component directory requires an init.py file
 (#9447)

* add-init-py-to-examples

* add-troubleshooting

* remove-extra-comment
---
 .../components-custom-components.mdx          |  7 ++++++
 docs/docs/Support/troubleshooting.mdx         | 24 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/docs/docs/Components/components-custom-components.mdx b/docs/docs/Components/components-custom-components.mdx
index 27eb9448c..3a3f747ca 100644
--- a/docs/docs/Components/components-custom-components.mdx
+++ b/docs/docs/Components/components-custom-components.mdx
@@ -243,9 +243,13 @@ By default, Langflow looks for custom components in the `/components` directory.
 
 If you're creating custom components in a different location using the `LANGFLOW_COMPONENTS_PATH` [environment variable](/environment-variables), components must be organized in a specific directory structure to be properly loaded and displayed in the visual editor:
 
+Each category directory **must** contain an `__init__.py` file for Langflow to properly recognize and load the components.
+This is a Python package requirement that ensures the directory is treated as a module.
+
 ```
 /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
 ```
 
@@ -257,6 +261,7 @@ For example, to add a component to the **Helpers** category, place it in the `he
 ```
 /app/custom_components/          # LANGFLOW_COMPONENTS_PATH
     └── helpers/                 # Displayed within the "Helpers" category
+        ├── __init__.py          # Required
         └── custom_component.py  # Your component
 ```
 
@@ -264,8 +269,10 @@ You can have multiple category folders to organize components into different cat
 ```
 /app/custom_components/
     ├── helpers/
+    │   ├── __init__.py
     │   └── helper_component.py
     └── tools/
+        ├── __init__.py
         └── tool_component.py
 ```
 
diff --git a/docs/docs/Support/troubleshooting.mdx b/docs/docs/Support/troubleshooting.mdx
index 06a6e2629..33e60f3b8 100644
--- a/docs/docs/Support/troubleshooting.mdx
+++ b/docs/docs/Support/troubleshooting.mdx
@@ -180,6 +180,30 @@ For troubleshooting advice for a third-party integration, see the information ab
 
 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 Langflow visual editor, try the following troubleshooting steps:
+
+1. Ensure your components follow the [required directory structure](https://docs.langflow.org/components-custom-components#directory-structure-requirements).
+    ```
+    /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
+    ```
+
+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 `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:
+
+    ```bash
+    uv run langflow run --components-path /path/to/your/custom/components
+    ```
+
+If you continue to experience issues, please [report them on GitHub](https://github.com/langflow-ai/langflow/issues) with details about your directory structure and component setup.
+
 ## See also
 
 - [Langflow GitHub Issues and Discussions](/contributing-github-issues)