docs: troubleshoot desktop errors from telemetry

[mendonk]

Preview build

Based on Desktop errors collected here, create easily searchable Troubleshooting items for the 6 most common error messages.

@mpawlow - you don't need to review the troubleshooting steps. I just want to confirm that I have the right errors the user will encounter and look for. If correct please approve.

@Empreiteiro Please review the troubleshooting suggestions.

Summary by CodeRabbit

• Documentation
  • Expanded the Langflow Desktop troubleshooting guide with comprehensive installation and startup issue guidance for Windows, macOS, and Linux, including OS-specific commands, dependency checks, health checks, and environment configuration steps.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 34dbec17-9e4f-45ee-b775-dd2bb91b5a47

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This documentation update expands troubleshooting guidance for Langflow Desktop across Windows, macOS, and Linux, replacing a narrow Windows-focused note with comprehensive installation and startup troubleshooting sections including dependency checks, OS-specific setup requirements, and verification steps.

Changes

Cohort / File(s)	Summary
Langflow Desktop Troubleshooting Documentation docs/docs/Support/troubleshooting.mdx	Restructured and significantly expanded "Langflow Desktop installation issues" section with new subsections for OSS installation sanity checks, health checks, missing dependencies (uv), Xcode Command Line Tools (macOS), Windows C++ build tools, manual uv installation, port verification, and PATH configuration. Adjusted phrasing in startup issues section (+94/-3 lines).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

🚥 Pre-merge checks | ✅ 7

✅ Passed checks (7 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: troubleshoot desktop errors from telemetry' accurately describes the main change—adding troubleshooting documentation for desktop errors collected from telemetry data.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Test Coverage For New Implementations	✅ Passed	This PR is a documentation-only change to troubleshooting.mdx that does not introduce code, components, features, or bug fixes. Test coverage verification is not applicable to documentation updates.
Test Quality And Coverage	✅ Passed	This pull request is a documentation-only change that modifies the troubleshooting guide without introducing any new code implementations or functions. Since the custom check evaluates test quality for code, it is not applicable to documentation changes.
Test File Naming And Structure	✅ Passed	Pull request only modifies documentation (troubleshooting.mdx) with no test files added, modified, or involved.
Excessive Mock Usage Warning	✅ Passed	The custom check for excessive mock usage in test files is not applicable to this pull request. This PR exclusively modifies the documentation file docs/docs/Support/troubleshooting.mdx with no test files included.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-troubleshoot-desktop-from-telemetry

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @docs/docs/Support/troubleshooting.mdx:
- Around line 134-147: Update the heading and any occurrences of "MacOS" to
Apple’s preferred "macOS" (e.g., change the heading "### [MacOS] Failed to
install Langflow OSS: Xcode Command Line Tools are not installed" to use
"macOS"); wrap the sentence "**The installation may take over 20 minutes**." in
a visible admonition block (e.g., add a :::warning admonition around that line)
to improve visibility while keeping the existing steps and commands like
"xcode-select --install" and "xcode-select -p" unchanged.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8da8fdc and 0aec8b4.

📒 Files selected for processing (1)

• docs/docs/Support/troubleshooting.mdx

🧰 Additional context used

📓 Path-based instructions (1)

docs/docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/docs_development.mdc)

docs/docs/**/*.{md,mdx}: Markdown files must include YAML frontmatter with title, description, and sidebar_position
Use Docusaurus admonitions (:::tip, :::warning, :::danger) for important information, warnings, and critical alerts
Code blocks must include a title attribute and specify the language (e.g., ```python title="filename.py")
All images must use descriptive alt text that clearly explains what the image shows
Use sentence case for headers and proper capitalization for terminology: Langflow, Component, Flow, API, JSON
Use bold formatting for UI elements, italic for emphasis, and backticks for inline code
Use second person ('you') for instructions and present tense for current features in documentation content
Tables in documentation must include columns for Input/Output name, Type, Required (if applicable), and Description
Internal links between documentation pages must be functional and properly formatted using Docusaurus link syntax

Files:

• docs/docs/Support/troubleshooting.mdx

🧠 Learnings (1)

📓 Common learnings

Learnt from: edwinjosechittilappilly
Repo: langflow-ai/langflow PR: 0
File: :0-0
Timestamp: 2025-08-07T20:23:23.569Z
Learning: The Langflow codebase has an excellent structlog implementation that follows best practices, with proper global configuration, environment-based output formatting, and widespread adoption across components. The main cleanup needed is updating starter project templates and documentation examples that still contain legacy `from loguru import logger` imports.

Learnt from: CR
Repo: langflow-ai/langflow PR: 0
File: .cursor/rules/docs_development.mdc:0-0
Timestamp: 2025-06-23T12:46:29.953Z
Learning: When writing documentation for Langflow using Docusaurus, always use professional but approachable tone, second person voice for instructions, and present tense for current features.

🪛 LanguageTool

docs/docs/Support/troubleshooting.mdx

[uncategorized] ~134-~134: The operating system from Apple is written “macOS”.
Context: ...c`. 4. Restart Langflow Desktop. ### [MacOS] Failed to install Langflow OSS: Xcode ...

(MAC_OS)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build-and-deploy

🔇 Additional comments (5)

docs/docs/Support/troubleshooting.mdx (5)

84-89: LGTM!

Clear section introduction with helpful cross-reference to the Desktop logs documentation.

---

90-103: LGTM!

Clear troubleshooting steps with OS-specific paths. The guidance to clear the virtual environment and verify Python installation is practical.

---

104-132: LGTM!

The port check commands and PATH configuration instructions are accurate and well-organized by OS.

---

149-177: LGTM!

Comprehensive Windows troubleshooting with multiple installation options (PowerShell and pip) and clear PATH configuration guidance.

---

191-191: LGTM!

Minor wording improvement for consistency with the directive tone used throughout the document.

[mpawlow]

@mendonk

Code Review 1

• ✅ Approved / LGTM 🚀
• See PR comments: (a) to (g) for "Info" / "Minor" comments (for optional consideration)

[mpawlow]

@mendonk

Code Review 1

• ✅ Approved / LGTM 🚀
• See PR comments: (a) to (f) for "Info" / "Minor" comments (for optional consideration)

[mpawlow]

@mendonk

Code Review 1

• ✅ Approved / LGTM 🚀
• See PR comments: (a) to (g) for "Info" / "Minor" comments (for optional consideration)

[mpawlow]

@mendonk
⚠️ If you see any weirdly incomplete or duplicate comments, its because public GitHub is having stability issues (had to resubmit comments multiple times due to server errors)

[github-actions]

Build successful! ✅
Deploying docs draft.
Deploy successful! View draft