/troubleshoot-deploy

name: webflow-code-component:troubleshoot-deploy
description: Debug deployment failures for Webflow Code Components. Analyzes error messages, identifies root causes, and provides specific fixes for common issues.
compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli
metadata:
  author: webflow
  version: "1.1"

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](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

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