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 log has 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:
# Regenerate token, then:
export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token
npx webflow library shareMissing Dependencies:
npm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/reactSSR Issues:
// Wrap browser APIs in useEffect or disable SSR:
declareComponent(Component, { options: { ssr: false } });Missing Styles:
// In .webflow.tsx, import styles:
import "./Component.module.css";Debugging Commands
# 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 --noEmitValidation
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