Webflow Code Component:troubleshoot Deploy Agent Skill

Troubleshoot Deploy

Debug and fix deployment issues for Webflow Code Components.

When to Use This Skill

Use when:

• webflow library share failed 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 share

Missing Dependencies:

npm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react

SSR 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 --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