ERROR CATALOG

references/ERROR_CATALOG.mdMarkdown15 KBView on GitHub

Detailed solutions for common deployment errors.

Diagnostic Flowchart

Use this decision tree to quickly find the right error category:

ERROR CATALOG · Webflow Code Component:troubleshoot Deploy · webflow/webflow-skills · Skills Docs

Deploy failed?
├── Error mentions "token", "auth", or "permission"?
│   └── Go to: Authentication Errors
├── Error mentions "module not found", "TypeScript", or "syntax"?
│   └── Go to: Build Errors
├── Error mentions "bundle size" or "50MB"?
│   └── Go to: Bundle Errors
├── Error mentions "429", "timeout", or "network"?
│   └── Go to: Network Errors
├── Error mentions "webflow.json", "no components", or "invalid JSON"?
│   └── Go to: Configuration Errors
├── Component deployed but not rendering or missing styles?
│   └── Go to: Runtime Errors
├── Error mentions "heap", "memory", or "JavaScript heap"?
│   └── Go to: Memory Errors
└── None of the above?
    └── Go to: Still Broken? (bottom of this file)

🔧 Fix: Authentication Failed

**Step 1: Regenerate API Token**

1. Go to Webflow Dashboard
2. Navigate to Workspace Settings
3. Find "Apps & Integrations" → "Manage"
4. Under "Workspace API Access":
   - Revoke existing token (if any)
   - Click "Generate API Token"
   - Copy the new token

**Step 2: Update Token**

Option A - Environment variable:
```bash
export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token

Wrong prop type:

// ❌ Passing string when number expected
<Component count="5" />

// ✅ Correct type
<Component count={5} />

Missing prop:

// ❌ Missing required prop
<Component />

// ✅ Include required prop
<Component title="Hello" />

Incorrect import:

// ❌ Wrong import
import { props } from "@webflow/react";

// ✅ Correct import
import { props } from "@webflow/data-types";

File extension is correct:
- .tsx for TypeScript + JSX
- .jsx for JavaScript + JSX
- .ts for TypeScript (no JSX)

tsconfig.json has JSX support:

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

No syntax errors in JSX:

// ❌ Common mistake - missing closing tag
<div>
  <span>Hello
</div>

// ✅ Correct
<div>
  <span>Hello</span>
</div>

Heavy Package	Size	Alternative
moment	~300KB	date-fns (~30KB)
lodash	~530KB	lodash-es (tree-shakeable)
three.js	~600KB	Dynamic import
@mui/material	~500KB	Individual imports

import { lazy, Suspense } from "react";

const HeavyComponent = lazy(() => import("./HeavyComponent"));

export const MyComponent = () => (
  <Suspense fallback={<div>Loading...</div>}>
    <HeavyComponent />
  </Suspense>
);

// ❌ Will break during SSR
export const Component = () => {
  const width = window.innerWidth;
  return <div>{width}</div>;
};

// ✅ SSR-safe
export const Component = () => {
  const [width, setWidth] = useState(0);

  useEffect(() => {
    setWidth(window.innerWidth);
  }, []);

  return <div>{width || "Loading..."}</div>;
};

// ❌ Multiple roots
export const Component = () => (
  <>
    <div>One</div>
    <div>Two</div>
  </>
);

// ✅ Single root
export const Component = () => (
  <div>
    <div>One</div>
    <div>Two</div>
  </div>
);

// Button.webflow.tsx
import { declareComponent } from "@webflow/react";
import { Button } from "./Button";
import "./Button.module.css";  // ← Must be here!

declareComponent(Button, { ... });

Ensure globals.css contains @import "tailwindcss";
Ensure globals.ts imports globals.css:
```
// globals.ts
import "./globals.css";
```

Ensure webflow.json references the globals file:

{
  "library": {
    "globals": "./src/globals.ts"
  }
}

Ensure PostCSS is configured with @tailwindcss/postcss in postcss.config.mjs

Field	Required	Description
name	Yes	Library name in Designer
components	Yes	Glob pattern for .webflow.tsx files
globals	No	Path to globals/decorators
bundleConfig	No	Custom webpack config

// ❌ Trailing comma
{ "library": { "name": "My Lib", } }

// ❌ Comments not allowed
{ "library": { "name": "My Lib" /* comment */ } }

// ✅ Valid JSON
{ "library": { "name": "My Lib" } }

Extract shared code into a separate file that both components import
Use dynamic imports for one direction of the dependency:
```
const ComponentB = lazy(() => import("./ComponentB"));
```
Restructure — if two components depend on each other, they may belong in the same file or need a shared parent


---

## Still Broken?

If none of the solutions above resolve your issue, gather the following information before escalating:

### Data to Collect

```bash
# 1. Recent deploy logs
npx webflow library log

# 2. Verbose deploy 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. webflow.json contents
cat webflow.json

ERROR CATALOG

Diagnostic Flowchart

ERROR CATALOG

Diagnostic Flowchart

Authentication Errors

“Authentication failed”

Where to Get Help