Framer Common Errors

Overview

Diagnostic reference for common Framer plugin, component, and Server API errors with actionable fixes.

Error Reference

Plugin Not Appearing in Editor

Cause: Dev server not running or plugin not registered.

Fix:

npm run dev  # Start Vite dev server
# Then in Framer: Plugins > Development > select your plugin

framer is not defined

Cause: Calling framer API outside the Framer editor iframe context.

Fix: The framer global from framer-plugin only works inside the editor. For server-side access, use framer-api package instead.

// Plugin (editor): import { framer } from 'framer-plugin';
// Server (headless): import { framer } from 'framer-api';

Component Renders Blank on Canvas

Cause: Runtime error in component code (swallowed by Framer).

Fix: Open Framer's browser console (right-click > Inspect) and check for errors. Common causes:

• Missing export default on component
• Undefined props without defaults
• Fetch errors from blocked CORS requests

addPropertyControls Not Showing

Cause: Called on wrong component or wrong import.

Fix:

// Must import from 'framer', not 'framer-plugin'
import { addPropertyControls, ControlType } from 'framer';

// Must be called AFTER the component definition
export default function MyComponent(props) { /* ... */ }
addPropertyControls(MyComponent, { /* ... */ });

Code Override Not Applying

Cause: Override function not returning correct shape.

Fix: Overrides must return an Override type object (Framer Motion props):

import { Override } from 'framer';

// Correct — returns Override
export function MyOverride(): Override {
  return { whileHover: { scale: 1.1 } };
}

// Wrong — missing return type, or returning JSX

Server API WebSocket connection failed

Cause: Invalid API key, wrong site ID, or network blocking WSS.

Fix:

# Verify API key is valid
echo $FRAMER_API_KEY | head -c 20  # Should start with 'framer_sk_'

# Verify site ID
echo $FRAMER_SITE_ID

# Test WebSocket connectivity
curl -s https://api.framer.com/health || echo "Cannot reach Framer API"

CMS Collection field type invalid

Cause: Using unsupported field type string.

Fix: Valid types: string, formattedText, number, boolean, date, link, image, color, enum, slug

CORS Errors in Code Components

Cause: Fetch API in components blocked by browser CORS policy.

Fix: Use a CORS proxy or ensure your API returns proper Access-Control-Allow-Origin headers. Framer components run in the browser — same CORS rules apply.

Quick Diagnostic

# Check if Framer API is reachable
curl -s https://api.framer.com/health

# Verify npm packages
npm list framer-plugin framer-api framer

# Check for common issues in code
grep -r "from 'framer'" src/ --include="*.tsx" | head -10

Resources

• Framer Developer Docs
• Plugin Troubleshooting
• Framer Changelog

Next Steps

For debugging tools, see framer-debug-bundle.