webflow-code-component:troubleshoot-deploy
Debug deployment failures for Webflow Code Components. Analyzes error messages, identifies root causes, and provides specific fixes for common issues.
What this skill does
# 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:**
```bash
# Regenerate token, then:
export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token
npx webflow library share
```
**Missing Dependencies:**
```bash
npm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
```
**SSR Issues:**
```typescript
// Wrap browser APIs in useEffect or disable SSR:
declareComponent(Component, { options: { ssr: false } });
```
**Missing Styles:**
```typescript
// In .webflow.tsx, import styles:
import "./Component.module.css";
```
## Debugging Commands
```bash
# 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
Related in Design
contribute
IncludedLocal-only OSS contribution command center. Auto-refreshes the user's in-flight PR and issue state on invoke so conversations start with full context — no need to brief Claude on what's in flight. Helps the user find issues to contribute to on GitHub, builds per-repo dossiers of what each upstream expects (CLA, DCO, branch convention, AI policy, draft-first, review bots, issue templates), runs deterministic gates before any external action so AI-assisted contributions don't reach maintainers as slop. State is markdown-only: candidate files at ~/.contribute-system/candidates/, repo dossiers at ~/.contribute-system/research/, append-only event log at ~/.contribute-system/log.jsonl. No database, no cloud calls. Use when the user asks about their PRs / issues / contributions, wants to find new work to take on, claim an issue, build/refresh a repo's dossier, or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR status", "find a contribution", "claim issue X", "draft a Design Issue for Y", "refresh dossier for Z".
architectural-analysis
IncludedUser-triggered deep architectural analysis of a codebase or scoped subtree across eight modes — information architecture, data flow, integration points, UI surfaces, interaction patterns, data model, control flow, and failure modes. This skill should be used when the user asks to "diagram this codebase," "map the architecture," "show the data flow," "give me an ERD," "trace control flow," "find the integration points," "verify the layout pattern," "audit the UX architecture," or any similar request whose primary deliverable is mermaid diagrams plus cited reports under docs/architecture/. Dispatches haiku/sonnet sub-agents in parallel for per-mode exploration, then verifies every citation mechanically before any node lands in a diagram. Not for one-off prose explanations of code (use code-explanation) or for high-level system design from scratch (use system-design).
mcp
IncludedModel Context Protocol (MCP) server development and tool management. Languages: Python, TypeScript. Capabilities: build MCP servers, integrate external APIs, discover/execute MCP tools, manage multi-server configs, design agent-centric tools. Actions: create, build, integrate, discover, execute, configure MCP servers/tools. Keywords: MCP, Model Context Protocol, MCP server, MCP tool, stdio transport, SSE transport, tool discovery, resource provider, prompt template, external API integration, Gemini CLI MCP, Claude MCP, agent tools, tool execution, server config. Use when: building MCP servers, integrating external APIs as MCP tools, discovering available MCP tools, executing MCP capabilities, configuring multi-server setups, designing tools for AI agents.
react-native-skia
IncludedDesign, build, debug, and optimise high-polish animated graphics in React Native or Expo using @shopify/react-native-skia, Reanimated, and Gesture Handler. Use when the user wants canvas-driven UI, shaders, paths, rich text, image filters, sprite fields, Skottie, video frames, snapshots, web CanvasKit setup, or performance tuning for custom motion-heavy elements such as loaders, hero art, cards, charts, progress indicators, particle systems, or gesture-driven surfaces. Also use when the user asks for fluid, glow, glass, blob, parallax, 60fps/120fps, or GPU-friendly animated effects in React Native, even if they do not explicitly say "Skia". Do not use for ordinary form/layout work with standard views.
plaid
IncludedProduct Led AI Development — guides founders from idea to launched product. Six capabilities: Idea (discover a product idea), Validate (pressure-test the idea against fatal flaws, problem reality, competition, and 2-week MVP feasibility), Plan (vision intake + document generation), Design (translate image references into a design.md spec), Launch (go-to-market strategy), and Build (roadmap execution). Use when someone says "PLAID", "plaid idea", "help me find an idea", "product idea", "idea from my business", "idea from my expertise", "plaid validate", "validate my idea", "pressure-test", "is this idea good", "find fatal flaws", "validate the problem", "plan a product", "define my vision", "generate a PRD", "product strategy", "plaid design", "design from image", "translate image to design", "create design.md", "extract design tokens", "plaid launch", "go-to-market", "launch plan", "GTM strategy", "launch playbook", "plaid build", "build the app", "start building", or "execute the roadmap".
nextjs-framer-motion-animations
IncludedAdds production-safe Motion for React or Framer Motion animations to Next.js apps, including reveal, hover and tap micro-interactions, whileInView, stagger, AnimatePresence, layout and layoutId transitions, reorder, scroll-linked UI, and lightweight route-content transitions. Use when the user asks to add, refactor, or debug Motion or Framer Motion in App Router or Pages Router codebases, especially around server/client boundaries, reduced motion, LazyMotion, bundle size, hydration, or route transitions. Avoid for GSAP-style timelines, WebGL or 3D scenes, heavy scroll storytelling, or CSS-only effects unless Motion is explicitly requested.