troubleshoot-deploy
starsforks
How to install troubleshoot-deploy?
webflow/webflow-skills/troubleshoot-deploy
$npx -y skills add webflow/webflow-skills --skill troubleshoot-deployDebug deployment failures for Webflow Code Components. Analyzes error messages, identifies root causes, and provides specific fixes for common issues.
SKILL.md
| 1 | # Troubleshoot Deploy |
| 2 | |
| 3 | Debug and fix deployment issues for Webflow Code Components. |
| 4 | |
| 5 | ## When to Use This Skill |
| 6 | |
| 7 | **Use when:** |
| 8 | - `webflow library share` failed with an error |
| 9 | - Components deployed but aren't working correctly |
| 10 | - User shares an error message from deployment |
| 11 | - Bundle or compilation errors occurred |
| 12 | |
| 13 | **Do NOT use when:** |
| 14 | - Deployment hasn't been attempted yet (use deploy-guide instead) |
| 15 | - Validating before deployment (use pre-deploy-check instead) |
| 16 | - General code quality issues (use component-audit instead) |
| 17 | |
| 18 | ## Instructions |
| 19 | |
| 20 | ### Phase 1: Gather Information |
| 21 | |
| 22 | 1. **Get error details**: |
| 23 | - Ask for exact error message |
| 24 | - Request output from `npx webflow library share` |
| 25 | - Check if `npx webflow library log` has additional info |
| 26 | |
| 27 | 2. **Understand context**: |
| 28 | - First deploy or update? |
| 29 | - Recent changes made? |
| 30 | - Working previously? |
| 31 | |
| 32 | ### Phase 2: Diagnose |
| 33 | |
| 34 | 3. **Identify error category**: |
| 35 | - Authentication errors |
| 36 | - Build/compilation errors |
| 37 | - Bundle size errors |
| 38 | - Network/upload errors |
| 39 | - Configuration errors |
| 40 | |
| 41 | 4. **Analyze root cause**: |
| 42 | - Parse error message |
| 43 | - Check common causes |
| 44 | - Identify specific issue |
| 45 | |
| 46 | ### Phase 3: Provide Solution |
| 47 | |
| 48 | 5. **Give specific fix**: |
| 49 | - Step-by-step resolution |
| 50 | - Code examples if needed |
| 51 | - Verification steps |
| 52 | |
| 53 | 6. **Prevent recurrence**: |
| 54 | - Explain why it happened |
| 55 | - Suggest preventive measures |
| 56 | |
| 57 | ## Common Error Reference |
| 58 | |
| 59 | For detailed solutions to each error, see [references/ERROR_CATALOG.md](references/ERROR_CATALOG.md). |
| 60 | |
| 61 | ### Quick Reference |
| 62 | |
| 63 | | Error | Category | Quick Fix | |
| 64 | |-------|----------|-----------| |
| 65 | | "Authentication failed" | Auth | Regenerate API token in Workspace Settings | |
| 66 | | "Insufficient permissions" | Auth | Check workspace role and token | |
| 67 | | "Module not found" | Build | `npm install --save-dev @webflow/react` | |
| 68 | | "TypeScript errors" | Build | Run `npx tsc --noEmit` to find error | |
| 69 | | "Unexpected token" | Build | Check file extension is `.tsx` | |
| 70 | | "Bundle size exceeds limit" | Bundle | Tree-shake imports, lazy load heavy components | |
| 71 | | "Component not rendering" | Runtime | Check SSR issues, browser console | |
| 72 | | "Styles not appearing" | Runtime | Import CSS in .webflow.tsx file | |
| 73 | | "webflow.json not found" | Config | Create webflow.json in project root | |
| 74 | | "No components found" | Config | Check glob pattern and file extension | |
| 75 | | "Invalid JSON in webflow.json" | Config | Fix JSON syntax (trailing commas, comments) | |
| 76 | | "429 Too Many Requests" | Network | Wait 60 seconds and retry | |
| 77 | | "Request timed out" | Network | Check connectivity, proxy, Webflow status | |
| 78 | | "JavaScript heap out of memory" | Memory | `NODE_OPTIONS="--max-old-space-size=4096"` | |
| 79 | | "Circular dependency" | Build | Extract shared code, break import cycles | |
| 80 | |
| 81 | ### Most Common Fixes |
| 82 | |
| 83 | **Authentication:** |
| 84 | ```bash |
| 85 | # Regenerate token, then: |
| 86 | export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token |
| 87 | npx webflow library share |
| 88 | ``` |
| 89 | |
| 90 | **Missing Dependencies:** |
| 91 | ```bash |
| 92 | npm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react |
| 93 | ``` |
| 94 | |
| 95 | **SSR Issues:** |
| 96 | ```typescript |
| 97 | // Wrap browser APIs in useEffect or disable SSR: |
| 98 | declareComponent(Component, { options: { ssr: false } }); |
| 99 | ``` |
| 100 | |
| 101 | **Missing Styles:** |
| 102 | ```typescript |
| 103 | // In .webflow.tsx, import styles: |
| 104 | import "./Component.module.css"; |
| 105 | ``` |
| 106 | |
| 107 | ## Debugging Commands |
| 108 | |
| 109 | ```bash |
| 110 | # Check recent deploy logs |
| 111 | npx webflow library log |
| 112 | |
| 113 | # Verbose deploy output (shows detailed errors) |
| 114 | npx webflow library share --verbose |
| 115 | |
| 116 | # Type check without deploying |
| 117 | npx tsc --noEmit |
| 118 | ``` |
| 119 | |
| 120 | ## Validation |
| 121 | |
| 122 | The issue is resolved when all of the following are true: |
| 123 | |
| 124 | | Success Criteria | How to Verify | |
| 125 | |-----------------|---------------| |
| 126 | | Deploy completes without errors | `npx webflow library share` exits cleanly | |
| 127 | | Components appear in Designer | Open Add panel in Designer and find your library | |
| 128 | | Import logs confirm success | `npx webflow library log` shows successful import | |
| 129 | |
| 130 | ## Guidelines |
| 131 | |
| 132 | ### Error Analysis Process |
| 133 | |
| 134 | 1. **Read the full error message** - Often contains the solution |
| 135 | 2. **Check the error category** - Auth, build, bundle, or runtime |
| 136 | 3. **Look for file paths** - Points to exact location |
| 137 | 4. **Check line numbers** - For code errors |
| 138 | 5. **Search error message** - May be a known issue |
| 139 | |
| 140 | ### When to Escalate |
| 141 | |
| 142 | If none of the solutions work, gather this data before escalating: |
| 143 | |
| 144 | 1. **Deploy logs**: `npx webflow library log` |
| 145 | 2. **Verbose output**: `npx webflow library share --verbose` |
| 146 | 3. **Node.js version**: `node -v` |
| 147 | 4. **Package versions**: `npm list @webflow/webflow-cli @webflow/data-types @webflow/react` |
| 148 | 5. **Configuration**: Contents of `webflow.json` |
| 149 | 6. **Error message**: Full error output (not just the summary line) |
| 150 | |
| 151 | Then: |
People who liked this also viewed
6 picksType
- web-design-guidelinesReview UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".SkillsJul 2026
- lark-slides飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 SkillsJul 2026
- design-taste-frontendTaste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop SkillsJul 2026
- ui-ux-pro-maxUI/UX design intelligence for web and mobile. Searchable local database with 84 styles, 192 color palettes, 74 font pairings, 192 product types, 98 UX guidelines, 104 icon entries, 16 GSAP motion presSkillsJul 2026
- caveman-helpQuick-reference card for all caveman modes, skills, and commands. One-shot display, not a persistent mode. Trigger: /caveman-help, "caveman help", "what caveman commands", "how do I use caveman".SkillsJul 2026
- codebase-designShared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-nSkillsJul 2026
