docs: Add TROUBLESHOOTING.md guide for common development issues #7738
Conversation
🎭 Playwright Test Results❌ Some tests failed ⏰ Completed at: 12/24/2025, 06:31:11 PM UTC 📈 Summary
📊 Test Reports by Browser
🎉 Click on the links above to view detailed test results for each browser configuration. |
🎨 Storybook Build Status✅ Build completed successfully! ⏰ Completed at: 12/24/2025, 06:22:13 PM UTC 🔗 Links🎉 Your Storybook is ready for review! |
Bundle Size ReportSummary
Category Glance Per-category breakdownApp Entry Points — 3.19 MB (baseline 3.19 MB) • ⚪ 0 BMain entry bundles and manifests
Graph Workspace — 995 kB (baseline 995 kB) • ⚪ 0 BGraph editor runtime, canvas, workflow orchestration
Views & Navigation — 6.54 kB (baseline 6.54 kB) • ⚪ 0 BTop-level views, pages, and routed surfaces
Panels & Settings — 295 kB (baseline 295 kB) • ⚪ 0 BConfiguration panels, inspectors, and settings screens
UI Components — 196 kB (baseline 196 kB) • ⚪ 0 BReusable component library chunks
Data & Services — 12.5 kB (baseline 12.5 kB) • ⚪ 0 BStores, services, APIs, and repositories
Utilities & Hooks — 1.41 kB (baseline 1.41 kB) • ⚪ 0 BHelpers, composables, and utility bundles
Vendor & Third-Party — 9.1 MB (baseline 9.1 MB) • ⚪ 0 BExternal libraries and shared vendor chunks
Other — 3.44 MB (baseline 3.44 MB) • ⚪ 0 BBundles that do not match a named category
|
Added comprehensive troubleshooting guide to help developers resolve common issues: - Development server problems (nx serve hanging) - Build and TypeScript errors - Dependency and package management issues - Testing problems - Git and branch issues Includes: - Mermaid flowchart for quick diagnostics - FAQ format with symptoms and solutions - Step-by-step resolution instructions - Community support links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
snomiao
force-pushed
the
docs/add-troubleshooting-guide
branch
from
afc2f10 to
7caee0e
Compare
dosubot
bot
added
the
size:L
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive troubleshooting guide (TROUBLESHOOTING.md) to help developers resolve common development issues encountered when working with the ComfyUI Frontend project. The guide was created in response to recurring questions in the #noobie-questions channel about development server issues.
Key changes:
- Created a new FAQ-style troubleshooting guide with a Mermaid diagnostic flowchart
- Documented solutions for development server, build, dependency, testing, and Git issues
- Included links to community support resources and contribution guidelines
| 2. **Use a different port:** | ||
| ```bash | ||
| pnpm dev --port 3000 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The command pnpm dev --port 3000 may not work as expected. Looking at the package.json, pnpm dev maps to nx serve, and the vite configuration doesn't show explicit port configuration options being passed through nx to vite. The standard way to change the port in Vite-based projects is typically through environment variables or the vite.config file. Consider verifying this command works, or provide an alternative solution such as modifying the vite.config.mts or using environment variables.
| 2. **Use a different port:** | |
| ```bash | |
| pnpm dev --port 3000 | |
| ``` | |
| 2. **Use a different port (Vite/Nx-safe):** | |
| - **Option A – via `.env` file (recommended):** | |
| 1. Create or edit a local env file (for example): | |
| ```bash | |
| # .env.local | |
| VITE_DEV_SERVER_PORT=3000 | |
| ``` | |
| 2. Make sure your `vite.config.mts` reads this variable and sets `server.port` accordingly. | |
| 3. Start the dev server normally: | |
| ```bash | |
| pnpm dev | |
| ``` | |
| - **Option B – via `vite.config.mts`:** | |
| 1. Open `vite.config.mts`. | |
| 2. Set the dev server port explicitly (example): | |
| ```ts | |
| export default defineConfig({ | |
| server: { | |
| port: 3000, | |
| }, | |
| }); | |
| ``` | |
| 3. Run: | |
| ```bash | |
| pnpm dev | |
| ``` |
|
|
||
| 3. **Check Node version matches CI:** | ||
| ```bash | ||
| node --version # Should be v24.x |
There was a problem hiding this comment.
The Node version reference is inconsistent with the project's .nvmrc file. The .nvmrc file specifies version "24" (without the "v" prefix or ".x" suffix), and the project documentation typically refers to "Node.js (v24)" or just "24". For consistency with the rest of the documentation and to avoid confusion, change "v24.x" to match the standard format used elsewhere in the project.
| node --version # Should be v24.x | |
| node --version # Should be v24 |
| CI=true pnpm test | ||
| ``` | ||
|
|
||
| 2. **Clear test cache:** | ||
| ```bash | ||
| pnpm test --clearCache |
There was a problem hiding this comment.
The test command pnpm test --clearCache is incorrect. Based on the package.json scripts, the project uses pnpm test:unit for running unit tests (which uses vitest), and vitest doesn't have a --clearCache option. Instead, vitest uses --no-cache to disable caching. Additionally, there's no generic pnpm test command defined in the package.json. The correct command should be pnpm test:unit --no-cache or to clear vitest's cache directory manually.
| CI=true pnpm test | |
| ``` | |
| 2. **Clear test cache:** | |
| ```bash | |
| pnpm test --clearCache | |
| CI=true pnpm test:unit |
- Clear test cache:
pnpm test:unit --no-cache
| ## Still Having Issues? | ||
|
|
||
| 1. **Search existing issues:** [GitHub Issues](https://github.com/Comfy-Org/ComfyUI_frontend/issues) | ||
| 2. **Ask the community:** [Discord #dev-frontend](https://discord.com/invite/comfyorg) |
There was a problem hiding this comment.
The Discord link points to the general invite URL https://discord.com/invite/comfyorg but references a specific channel "#dev-frontend". Discord invite links don't automatically direct users to specific channels. While the general invite is valid, users will need to manually navigate to the #dev-frontend channel after joining. Consider either removing the channel reference or clarifying that users should navigate to that channel after joining, to avoid confusion.
| 2. **Ask the community:** [Discord #dev-frontend](https://discord.com/invite/comfyorg) | |
| 2. **Ask the community:** Join our [Discord server](https://discord.com/invite/comfyorg) and navigate to the #dev-frontend channel. |
Summary
Adds a comprehensive
TROUBLESHOOTING.mdguide to help developers resolve common development issues.Motivation
a developer reported issues where
pnpm devwould get stuck on 'nx serve'. This highlighted the need for centralized troubleshooting documentation to help developers quickly resolve common issues without having to wait for help.Changes
TROUBLESHOOTING.mdwith FAQ-style documentationStructure
The guide includes:
Test Plan
🤖 Generated with Claude Code
┆Issue is synchronized with this Notion page by Unito