Skip to content

Commit 332738a

Browse files
aimurphyaimurphy
authored
docs: Build out Troubleshooting and Support documentation (#8662)
* change luna to enterprise support * community page updates * combine issues and discussions pages * move telemetry out of contribute * remove gerund title * rewrite issues page * fix 2 anchors * add troubleshooting page * move troubleshooting and extras from install * add some more issues * coderabbit
1 parent e8236db commit 332738a

9 files changed

Lines changed: 303 additions & 208 deletions

‎docs/docs/Contributing/contributing-community.md‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,33 @@ title: Join the Langflow community
33
slug: /contributing-community
44
---
55

6-
6+
There are several ways you can interact with the Langflow community and learn more about the Langflow project.
77

88
## Join the Langflow Discord server
99

1010
Join the [Langflow Discord Server](https://discord.gg/EqksyE2EX9) to ask questions and showcase your projects.
1111

1212
## Follow Langflow on X
1313

14-
Follow [@langflow_ai](https://twitter.com/langflow_ai) on X to get the latest news about Langflow.
14+
Follow [@langflow_ai](https://twitter.com/langflow_ai) on X to get the latest news about Langflow.
15+
16+
## Star Langflow on GitHub
17+
18+
If you like Langflow, you can star the [Langflow GitHub repository](https://github.com/langflow-ai/langflow).
19+
Stars help other users find Langflow more easily, and quickly understand that other users have found it useful.
20+
21+
Because Langflow is an open-source project, the more visible the repository is, the more likely the project is to attract [contributors](/contributing-how-to-contribute).
1522

16-
## Star Langflow on GitHub
23+
## Watch the GitHub repository
1724

18-
You can [star Langflow in GitHub](https://github.com/langflow-ai/langflow).
25+
You can watch the [Langflow GitHub repository](https://github.com/langflow-ai/langflow) to get notified about new releases and other repository activity.
1926

20-
By adding a star, other users will be able to find Langflow more easily, and see that it has been already useful for others.
27+
To get release notifications only, select **Releases only**.
2128

22-
## Watch the GitHub repository for releases
29+
If you select **Watching**, you will receive notifications about new releases as well as issues, discussions, and pull requests, if you are interested in that activity.
30+
For information about customizing repository notifications, see the [GitHub documentation on repository subscriptions](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions).
2331

24-
You can [watch Langflow in GitHub](https://github.com/langflow-ai/langflow). If you select **Watching** instead of **Releases only** you will receive notifications when someone creates a new issue or question. You can also specify that you want to be notified only about new issues, discussions, and PRs so you can try to help solve those issues.
32+
## Request enhancements and get help through GitHub
2533

34+
You can also submit feature requests and get help with Langflow through the GitHub repository.
35+
For more information, see [Get help and request enhancements](/contributing-github-issues).

‎docs/docs/Contributing/contributing-github-discussion-board.md‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎docs/docs/Contributing/contributing-github-issues.md‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,41 @@
11
---
2-
title: Request an enhancement or report a bug
2+
title: Get help and request enhancements
33
slug: /contributing-github-issues
44
---
55

6-
The [Issues page in the Langflow repo](https://github.com/langflow-ai/langflow/issues) is kept up to date with bugs, improvements, and feature requests. Labels are used to help with sorting and discovery of issues of interest. For an overview of the system Langflow uses to tag issues and pull requests, see the Langflow repo's [labels page](https://github.com/langflow-ai/langflow/labels).
6+
The Langflow GitHub repository is an integral part of the [Langflow community](/contributing-community).
7+
8+
In addition to general assistance with Langflow, the repository is the best place to report bugs and request enhancements to ensure that they are tracked by the Langflow project.
9+
10+
## GitHub issues
11+
12+
The [Issues page in the Langflow repository](https://github.com/langflow-ai/langflow/issues) is actively updated with bugs and feature requests.
13+
14+
:::tip
15+
The best way to promote a request or bug is to comment on an existing issue.
16+
Highly active issues are more likely to receive attention from contributors.
17+
18+
Before you report a bug or submit a feature request, search for existing similar issues.
19+
Use the [Langflow repository's labels](https://github.com/langflow-ai/langflow/labels) to help filter your search.
20+
:::
21+
22+
## GitHub discussions
23+
24+
If you need help with your code or Langflow in general, you can visit the [Langflow GitHub Discussions page](https://github.com/langflow-ai/langflow/discussions) or reach out through other [Langflow community](/contributing-community) channels.
25+
26+
The Langflow team doesn't provide individual support over email, and the team believes that public discussions help more users by virtue of their discoverability.
27+
28+
## Community guidelines and tips
29+
30+
Because the Issues and Discussion pages are public, the Langflow team asks that you follow these guidelines when submitting questions and issues:
31+
32+
* **Provide as many details as possible**: Simply stating that a feature doesn't work isn't helpful. The Langflow team needs details in order to recreate and find the issue.
33+
* **Explain what exactly went wrong**: Including error messages and descriptions of _how_ your code failed, not just the fact that it failed.
34+
* **Retrace your steps**: Explain what happened before the error, what you expected to happen instead of the error, and any recent changes you made, such as upgrading Langflow or a dependency.
35+
* **Describe your environment**: Include your operating system, Langflow version, Python version, and any other environment-related details that could have contributed to the issue.
36+
* **Include snippets of the code that failed**: Be sure to omit any sensitive values, and only provide parts relevant to the failure, rather than the entire script. Providing code snippets makes it much easier to reproduce errors, troubleshoot, and provide specific advice.
37+
* If your submission includes long sections of code, logs, or tracebacks, wrap them in [details tags](https://developer.mozilla.org/en/docs/Web/HTML/Element/details) (`<details> PASTE CODE HERE </details>`) to collapse the content and make it easier to read your submission.
38+
* **Omit sensitive information**: Other than the information available on your public GitHub profile, don't include sensitive or personally identifying data, such as security keys, full names, personal identification numbers, addresses, and phone numbers.
39+
* **Be kind**: Although bugs can be frustrating with any software, remember that your messages are read by real people who want to help. While you don't have to be saccharine, there's no need to be rude to get support.
40+
* Your issues and discussions are attached to your GitHub account, and they can be read by anyone on the internet, including current and potential employers and colleagues.
41+
* The Langlow repository is a public GitHub repository and, therefore, subject to the [GitHub Code of Conduct](https://docs.github.com/en/site-policy/github-terms/github.qkg1.topmunity-code-of-conduct).

‎docs/docs/Develop/install-custom-dependencies.md‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,37 @@ title: Install custom dependencies
33
slug: /install-custom-dependencies
44
---
55

6-
To install custom dependencies in your Langflow environment, add them with your package manager.
6+
Langflow provides optional dependency groups and support for custom dependencies to extend Langflow functionality.
77

8-
## Create a virtual environment for local testing
8+
## Install optional dependency groups
9+
10+
Langflow OSS provides optional dependency groups that extend its functionality.
11+
12+
These dependencies are listed in the [pyproject.toml](https://github.com/langflow-ai/langflow/blob/main/pyproject.toml#L191) file under `[project.optional-dependencies]`.
13+
14+
Install dependency groups using pip's `[extras]` syntax. For example, to install Langflow with the `postgresql` dependency group, enter the following command:
15+
16+
```bash
17+
uv pip install "langflow[postgresql]"
18+
```
19+
20+
To install multiple extras, use commas to separate each dependency group:
21+
22+
```bash
23+
uv pip install "langflow[deploy,local,postgresql]"
24+
```
25+
26+
## Install custom dependencies
27+
28+
To install your own custom dependencies in your Langflow environment, add them with your package manager.
29+
30+
If you're working within a cloned Langflow repository, add dependencies with `uv add` because there is already a `pyproject.toml` file for uv to reference:
31+
32+
```bash
33+
uv add langflow DEPENDENCY
34+
```
35+
36+
### Use a virtual environment to test custom dependencies
937

1038
When testing locally, use a virtual environment to isolate your dependencies and prevent conflicts with other Python projects.
1139

@@ -20,14 +48,17 @@ source YOUR_LANGFLOW_VENV/bin/activate
2048
uv pip install langflow matplotlib
2149
```
2250

23-
If you're working within a cloned Langflow repository, add dependencies with `uv add` because there is already a `pyproject.toml` file for uv to reference.
51+
If you're working within a cloned Langflow repository, add dependencies with `uv add` to reference the existing `pyproject.toml` file:
52+
2453
```bash
2554
uv add langflow matplotlib
2655
```
2756

2857
## Add dependencies to the Langflow project
2958

30-
When contributing to Langflow itself, add dependencies to the project's configuration. Langflow uses a workspace with two packages:
59+
When contributing to Langflow itself, add dependencies to the project's configuration.
60+
61+
Langflow uses a workspace with two packages:
3162

3263
* The `main` package (root level): For end-user features and main application code
3364
* The `base` package (in `src/backend/base`): For core functionality and shared code

‎docs/docs/Get-Started/get-started-installation.md‎

Lines changed: 29 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -30,20 +30,21 @@ Langflow can be installed in multiple ways:
3030

3131
</TabItem>
3232
<TabItem value="Windows" label="Windows">
33-
:::important
34-
Windows installations of Langflow Desktop require a C++ compiler, such as [Visual Studio](https://visualstudio.microsoft.com/downloads/), 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 visit the Visual Studio download link above.
35-
:::
3633

3734
1. Navigate to [Langflow Desktop](https://www.langflow.org/desktop).
3835
2. Click **Download Langflow**, enter your contact information, and then click **Download**.
3936
3. Open the **File Explorer**, and then navigate to **Downloads**.
4037
4. Double-click the downloaded `.msi` file, and then use the install wizard to install Langflow Desktop.
41-
6. When the installation completes, open the Langflow application.
38+
39+
:::important
40+
Windows installations of Langflow 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/).
41+
:::
42+
43+
5. When the installation completes, open the Langflow application.
4244

4345
After confirming that Langflow is running, create your first flow with the [Quickstart](/get-started-quickstart).
4446

4547
</TabItem>
46-
4748
</Tabs>
4849

4950
### Manage your version of Langflow Desktop
@@ -134,14 +135,16 @@ To delete the virtual environment, type `Remove-Item VENV_NAME`.
134135
</details>
135136

136137
2. To install Langflow, run the following command.
137-
```bash
138-
uv pip install langflow
139-
```
138+
139+
```bash
140+
uv pip install langflow
141+
```
140142

141143
3. After installation, start Langflow:
142-
```bash
143-
uv run langflow run
144-
```
144+
145+
```bash
146+
uv run langflow run
147+
```
145148

146149
4. To confirm that a local Langflow instance is running, navigate to the default Langflow URL `http://127.0.0.1:7860`.
147150
It can take a few minutes for Langflow to start.
@@ -150,165 +153,28 @@ After confirming that Langflow is running, create your first flow with the [Quic
150153

151154
### Manage Langflow OSS versions
152155

153-
To manage your Langflow version, use the following commands.
154-
155-
<details closed>
156-
<summary>Manage Langflow OSS versions</summary>
157-
158-
To upgrade Langflow to the latest version:
156+
:::important
157+
The Langflow team recommends installing new Langflow versions in a new virtual environment before upgrading your primary installation.
159158

160-
```bash
161-
uv pip install langflow -U
162-
```
163-
164-
To install a specific version of the Langflow package, add the required version to the command:
165-
166-
```bash
167-
uv pip install langflow==1.3.2
168-
```
159+
This allows you to [import flows](/concepts-flows#import-flow) from your existing installation and test them in the new version without disrupting your existing installation.
160+
In the event of breaking changes or bugs, your existing installation is preserved in a stable state.
161+
:::
169162

170-
To reinstall Langflow and all of its dependencies, add the `--force-reinstall` flag to the command:
171-
172-
```bash
173-
uv pip install langflow --force-reinstall
174-
```
175-
176-
</details>
163+
To manage your Langflow OSS version, use the following commands:
177164

165+
* Upgrade Langflow to the latest version: `uv pip install langflow -U`
166+
* Install a specific version of the Langflow package by adding the required version to the command, such as: `uv pip install langflow==1.3.2`
167+
* Reinstall Langflow and all of its dependencies: `uv pip install langflow --force-reinstall`
178168

179169
### Manage Langflow OSS dependencies
180170

181-
Langflow OSS provides optional dependency groups that extend its functionality.
182-
183-
These dependencies are listed in the [pyproject.toml](https://github.com/langflow-ai/langflow/blob/main/pyproject.toml#L191) file under `[project.optional-dependencies]`.
184-
185-
<details closed>
186-
<summary>Install dependency groups</summary>
187-
188-
Install dependency groups using pip's `[extras]` syntax. For example, to install Langflow with the `postgresql` dependency group, enter the following command:
189-
190-
```bash
191-
uv pip install "langflow[postgresql]"
192-
```
193-
194-
To install multiple extras, enter the following command:
195-
196-
```bash
197-
uv pip install "langflow[deploy,local,postgresql]"
198-
```
199-
200-
To add your own custom dependencies, see [Install custom dependencies](/install-custom-dependencies).
201-
202-
</details>
203-
204-
### Common OSS installation issues
205-
206-
This is a list of possible issues that you may encounter when installing and running Langflow.
207-
208-
<details>
209-
<summary>No <code>langflow.__main__</code> module</summary>
210-
211-
When you try to run Langflow with the command `langflow run`, you encounter the following error:
212-
213-
```bash
214-
> No module named 'langflow.__main__'
215-
```
216-
217-
1. Run `uv run langflow run` instead of `langflow run`.
218-
2. If that doesn't work, reinstall the latest Langflow version with `uv pip install langflow -U`.
219-
3. If that doesn't work, reinstall Langflow and its dependencies with `uv pip install langflow --pre -U --force-reinstall`.
220-
221-
</details>
222-
223-
<details>
224-
<summary>Langflow runTraceback</summary>
225-
226-
When you try to run Langflow using the command `langflow run`, you encounter the following error:
171+
Langflow OSS provides optional dependency groups and support for custom dependencies to extend Langflow functionality.
172+
For more information, see [Install custom dependencies](/install-custom-dependencies).
227173

228-
```bash
229-
> langflow runTraceback (most recent call last): File ".../langflow", line 5, in <module> from langflow.__main__ import mainModuleNotFoundError: No module named 'langflow.__main__'
230-
```
231-
232-
There are two possible reasons for this error:
233-
234-
1. You've 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`.
235-
2. Some version conflicts might have occurred during the installation process. Run `python -m pip install langflow --pre -U --force-reinstall` to reinstall Langflow and its dependencies.
236-
237-
</details>
238-
239-
<details>
240-
<summary>Something went wrong running migrations</summary>
241-
242-
```bash
243-
> Something went wrong running migrations. Please, run 'langflow migration --fix'
244-
```
245-
246-
Clear the cache by deleting the contents of the cache folder.
247-
248-
This folder can be found at:
249-
250-
- **Linux or WSL2 on Windows**: `home/<username>/.cache/langflow/`
251-
- **MacOS**: `/Users/<username>/Library/Caches/langflow/`
252-
253-
This error can occur during Langflow upgrades when the new version can't override `langflow-pre.db` in `.cache/langflow/`. Clearing the cache removes this file but also erases your settings.
254-
255-
If you wish to retain your files, back them up before clearing the folder.
256-
257-
</details>
258-
259-
<details>
260-
<summary>Langflow installation freezes at pip dependency resolution</summary>
261-
262-
Installing Langflow with `pip install langflow` slowly fails with this error message:
263-
264-
```text
265-
pip is looking at multiple versions of <<library>> to determine which version is compatible with other requirements. This could take a while.
266-
```
267-
268-
To work around this issue, install Langflow with [`uv`](https://docs.astral.sh/uv/getting-started/installation/) instead of `pip`.
174+
## Troubleshoot Langflow installation and startup issues
269175

270-
```text
271-
uv pip install langflow
272-
```
273-
274-
To run Langflow with uv:
275-
276-
```text
277-
uv run langflow run
278-
```
279-
280-
</details>
281-
282-
<details>
283-
<summary>Failed to build required package</summary>
284-
285-
When you try to install Langflow on Linux, installation fails because of outdated or missing packages.
286-
287-
```bash
288-
Resolved 455 packages in 18.92s
289-
× Failed to build `webrtcvad==2.0.10`
290-
├─▶ The build backend returned an error
291-
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
292-
```
293-
294-
1. Install the required build dependencies.
295-
296-
```bash
297-
sudo apt-get update
298-
sudo apt-get install build-essential python3-dev
299-
```
300-
301-
2. If upgrading your packages doesn't fix the issue, install `gcc` separately.
302-
303-
```bash
304-
sudo apt-get install gcc
305-
```
306-
307-
</details>
308-
309-
<details>
310-
<summary>Installation failure from <code>webrtcvad</code> package</summary>
176+
If you encounter an issue when installing or running Langflow, see [Troubleshoot Langflow](/troubleshoot).
311177

312-
If you experience an error from the `webrtcvad` package, run `uv pip install webrtcvad-wheels` in the virtual environment, and then try installing again.
178+
## Next steps
313179

314-
</details>
180+
After installing Langflow, build and run a flow with the [quickstart](/get-started-quickstart).

0 commit comments

Comments
 (0)