Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/jeremylongshore@tons-of-skills-marketplace/skills/.curated/framer-common-errors/SKILL.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill framer-common-errors. Copyright stays with the author (MIT).

Framer Common Errors

Prerequisites

An authorized site owner, an opaque incident ID, redacted diagnostics, and a safe staging reproduction path.

Instructions

Classify the issue as publishing, domain, asset, access, integration, or availability; reproduce with a staging page; apply the smallest reversible correction; verify both recovery and a safe failure response.

Output

Return a receipt with category, opaque correlation ID, action, verification, owner, and follow-up. Keep visitor data, tokens, and page content out of support evidence.

Error Handling

Pause publishing or integration changes on access, domain, or unexpected-destination failures. Use a rollback and route repeated failures to the site owner.

Examples

Break a fictional staging publish configuration, restore it, and verify the production site is untouched while the receipt contains no visitor or credential data.

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.