webflow-code-component:troubleshoot-deploy

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

1. Understand context:

• First deploy or update?
• Recent changes made?
• Working previously?

Phase 2: Diagnose

1. Identify error category:

• Authentication errors
• Build/compilation errors
• Bundle size errors
• Network/upload errors
• Configuration errors

1. Analyze root cause:

• Parse error message
• Check common causes
• Identify specific issue

Phase 3: Provide Solution

1. Give specific fix:

• Step-by-step resolution
• Code examples if needed
• Verification steps

1. 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