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

1. Get error details:
   • Ask for exact error message
   • Request output from npx webflow library share
   • Check if npx webflow library log has additional info
2. Understand context:
   • First deploy or update?
   • Recent changes made?
   • Working previously?

Phase 2: Diagnose

3. Identify error category:
   • Authentication errors
   • Build/compilation errors
   • Bundle size errors
   • Network/upload errors
   • Configuration errors
4. Analyze root cause:
   • Parse error message
   • Check common causes
   • Identify specific issue

Phase 3: Provide Solution

5. Give specific fix:
   • Step-by-step resolution
   • Code examples if needed
   • Verification steps
6. 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

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:

Guidelines

Error Analysis Process

1. Read the full error message - Often contains the solution
2. Check the error category - Auth, build, bundle, or runtime
3. Look for file paths - Points to exact location
4. Check line numbers - For code errors
5. Search error message - May be a known issue

When to Escalate

If none of the solutions work, gather this data before escalating:

1. Deploy logs: npx webflow library log
2. Verbose output: npx webflow library share --verbose
3. Node.js version: node -v
4. Package versions: npm list @webflow/webflow-cli @webflow/data-types @webflow/react
5. Configuration: Contents of webflow.json
6. 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