Troubleshoot Deploy
Debug and fix deployment issues for Webflow Code Components.
When to Use This Skill
Use when:
webflow library sharefailed with an error- Components deployed but aren't working correctly
- User shares an error message from deployment
- Bundle or compilation errors occurred
Do NOT use when:
- Deployment hasn't been attempted yet (use deploy-guide instead)
- Validating before deployment (use pre-deploy-check instead)
- General code quality issues (use component-audit instead)
Instructions
Phase 1: Gather Information
-
Get error details:
- Ask for exact error message
- Request output from
npx webflow library share - Check if
npx webflow library loghas additional info
-
Understand context:
- First deploy or update?
- Recent changes made?
- Working previously?
Phase 2: Diagnose
-
Identify error category:
- Authentication errors
- Build/compilation errors
- Bundle size errors
- Network/upload errors
- Configuration errors
-
Analyze root cause:
- Parse error message
- Check common causes
- Identify specific issue
Phase 3: Provide Solution
-
Give specific fix:
- Step-by-step resolution
- Code examples if needed
- Verification steps
-
Prevent recurrence:
- Explain why it happened
- Suggest preventive measures
Common Error Reference
For detailed solutions to each error, see references/ERROR_CATALOG.md.
Quick Reference
| Error | Category | Quick Fix |
|---|---|---|
| "Authentication failed" | Auth | Regenerate API token in Workspace Settings |
| "Insufficient permissions" | Auth | Check workspace role and token |
| "Module not found" | Build | npm install --save-dev @webflow/react |
| "TypeScript errors" | Build | Run npx tsc --noEmit to find error |
| "Unexpected token" | Build | Check file extension is .tsx |
| "Bundle size exceeds limit" | Bundle | Tree-shake imports, lazy load heavy components |
| "Component not rendering" | Runtime | Check SSR issues, browser console |
| "Styles not appearing" | Runtime | Import CSS in .webflow.tsx file |
| "webflow.json not found" | Config | Create webflow.json in project root |
| "No components found" | Config | Check glob pattern and file extension |
| "Invalid JSON in webflow.json" | Config | Fix JSON syntax (trailing commas, comments) |
| "429 Too Many Requests" | Network | Wait 60 seconds and retry |
| "Request timed out" | Network | Check connectivity, proxy, Webflow status |
| "JavaScript heap out of memory" | Memory | NODE_OPTIONS="--max-old-space-size=4096" |
| "Circular dependency" | Build | Extract shared code, break import cycles |
Most Common Fixes
Authentication:
bash# Regenerate token, then: export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token npx webflow library share
Missing Dependencies:
bashnpm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
SSR Issues:
typescript// Wrap browser APIs in useEffect or disable SSR: declareComponent(Component, { options: { ssr: false } });
Missing Styles:
typescript// In .webflow.tsx, import styles: import "./Component.module.css";
Debugging Commands
bash# Check recent deploy logs npx webflow library log # Verbose deploy output (shows detailed errors) npx webflow library share --verbose # Type check without deploying npx tsc --noEmit
Validation
The issue is resolved when all of the following are true:
| Success Criteria | How to Verify |
|---|---|
| Deploy completes without errors | npx webflow library share exits cleanly |
| Components appear in Designer | Open Add panel in Designer and find your library |
| Import logs confirm success | npx webflow library log shows successful import |
Guidelines
Error Analysis Process
- Read the full error message - Often contains the solution
- Check the error category - Auth, build, bundle, or runtime
- Look for file paths - Points to exact location
- Check line numbers - For code errors
- Search error message - May be a known issue
When to Escalate
If none of the solutions work, gather this data before escalating:
- Deploy logs:
npx webflow library log - Verbose output:
npx webflow library share --verbose - Node.js version:
node -v - Package versions:
npm list @webflow/webflow-cli @webflow/data-types @webflow/react - Configuration: Contents of
webflow.json - Error message: Full error output (not just the summary line)
Then:
- Check Webflow status page for outages
- Search the Webflow Community Forum for your error message
- Contact Webflow Support with the collected data above
