From 7caee0eebee93bd07758768391e383fdc5aafa76 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Dec 2025 06:10:01 +0000 Subject: [PATCH] docs: add TROUBLESHOOTING.md guide for common development issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- TROUBLESHOOTING.md | 260 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 000000000..5022bc0aa --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,260 @@ +# Troubleshooting Guide + +This guide helps you resolve common issues when developing ComfyUI Frontend. + +## Quick Diagnostic Flowchart + +```mermaid +flowchart TD + A[Having Issues?] --> B{What's the problem?} + B -->|Dev server stuck| C[nx serve hangs] + B -->|Build errors| D[Check build issues] + B -->|Dependency issues| E[Package problems] + B -->|Other| F[See FAQ below] + + C --> G{Tried quick fixes?} + G -->|No| H[Run: pnpm i] + G -->|Still stuck| I[Run: pnpm clean] + I --> J{Still stuck?} + J -->|Yes| K[Nuclear option:
pnpm dlx rimraf node_modules
&& pnpm i] + J -->|No| L[Fixed!] + H --> L + + D --> M[Run: pnpm build] + M --> N{Build succeeds?} + N -->|No| O[Check error messages
in FAQ] + N -->|Yes| L + + E --> H + + F --> P[Search FAQ or
ask in Discord] +``` + +## Frequently Asked Questions + +### Development Server Issues + +#### Q: `pnpm dev` or `nx serve` gets stuck and won't start + +**Symptoms:** +- Command hangs on "nx serve" +- Dev server doesn't respond +- Terminal appears frozen + +**Solutions (try in order):** + +1. **First attempt - Reinstall dependencies:** + ```bash + pnpm i + ``` + +2. **Second attempt - Clean build cache:** + ```bash + pnpm clean + ``` + +3. **Last resort - Full node_modules reset:** + ```bash + pnpm dlx rimraf node_modules && pnpm i + ``` + +**Why this happens:** +- Corrupted dependency cache +- Outdated lock files after branch switching +- Incomplete previous installations +- NX cache corruption + +--- + +#### Q: Port conflicts - "Address already in use" + +**Symptoms:** +- Error: `EADDRINUSE` or "port already in use" +- Dev server fails to start + +**Solutions:** + +1. **Find and kill the process using the port:** + ```bash + # On Linux/Mac + lsof -ti:5173 | xargs kill -9 + + # On Windows + netstat -ano | findstr :5173 + taskkill /PID /F + ``` + +2. **Use a different port:** + ```bash + pnpm dev --port 3000 + ``` + +--- + +### Build and Type Issues + +#### Q: TypeScript errors after pulling latest changes + +**Symptoms:** +- Type errors in files you didn't modify +- "Cannot find module" errors + +**Solutions:** + +1. **Rebuild TypeScript references:** + ```bash + pnpm build + ``` + +2. **Clean and reinstall:** + ```bash + pnpm clean && pnpm i + ``` + +3. **Restart your IDE's TypeScript server** + - VS Code: `Cmd/Ctrl + Shift + P` → "TypeScript: Restart TS Server" + +--- + +#### Q: "Workspace not found" or monorepo errors + +**Symptoms:** +- pnpm can't find workspace packages +- Import errors between packages + +**Solutions:** + +1. **Verify you're in the project root:** + ```bash + pwd # Should be in ComfyUI_frontend/ + ``` + +2. **Rebuild workspace:** + ```bash + pnpm install + pnpm build + ``` + +--- + +### Dependency and Package Issues + +#### Q: "Package not found" after adding a dependency + +**Symptoms:** +- Module not found after `pnpm add` +- Import errors for newly installed packages + +**Solutions:** + +1. **Ensure you installed in the correct workspace:** + ```bash + # For the main app + pnpm --filter web add + + # For the API client + pnpm --filter @comfyorg/api-client add + ``` + +2. **Clear pnpm cache:** + ```bash + pnpm store prune + pnpm install + ``` + +--- + +#### Q: Lock file conflicts after merge/rebase + +**Symptoms:** +- Git conflicts in `pnpm-lock.yaml` +- Dependency resolution errors + +**Solutions:** + +1. **Regenerate lock file:** + ```bash + rm pnpm-lock.yaml + pnpm install + ``` + +2. **Or accept upstream lock file:** + ```bash + git checkout --theirs pnpm-lock.yaml + pnpm install + ``` + +--- + +### Testing Issues + +#### Q: Tests fail locally but pass in CI + +**Symptoms:** +- Flaky tests +- Different results between local and CI + +**Solutions:** + +1. **Run tests in CI mode:** + ```bash + CI=true pnpm test + ``` + +2. **Clear test cache:** + ```bash + pnpm test --clearCache + ``` + +3. **Check Node version matches CI:** + ```bash + node --version # Should be v24.x + nvm use 24 # If using nvm + ``` + +--- + +### Git and Branch Issues + +#### Q: Changes from another branch appearing in my branch + +**Symptoms:** +- Uncommitted changes not related to your work +- Dirty working directory + +**Solutions:** + +1. **Stash and reinstall:** + ```bash + git stash + pnpm install + ``` + +2. **Check for untracked files:** + ```bash + git status + git clean -fd # Careful: removes untracked files! + ``` + +--- + +## 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) +3. **Create a new issue:** Include: + - Your OS and Node version (`node --version`) + - Steps to reproduce + - Full error message + - What you've already tried + +## Contributing to This Guide + +Found a solution to a common problem? Please: +1. Open a PR to add it to this guide +2. Follow the FAQ format above +3. Include the symptoms, solutions, and why it happens + +--- + +**Last Updated:** 2024-12-23