Server & Connectivity

modelBridge runs a local Node.js server on your machine that handles media extraction, file uploads, and API communication. This server starts automatically when you open the panel and is designed to be invisible — but occasionally things go wrong.

Local Server

How It Works

The backend server runs on port 3000 on localhost. It handles:

• Extracting video frames and images from your Premiere Pro timeline
• Uploading media to fal.ai for generation
• Downloading generated results
• Polling fal.ai for generation status
• Saving files and reports to disk

The server starts automatically when you open the modelBridge panel and shuts down when Premiere Pro closes.

Server Health Monitoring

A 90-second heartbeat monitors server health continuously. If the server becomes unresponsive:

1. The plugin detects the failure automatically
2. A restart is triggered within seconds
3. If recovery succeeds, you see no interruption
4. If recovery fails, an error message appears with a Reload button

”Connection interrupted” Error

This means the plugin lost contact with the local server. Common causes:

• System sleep/wake — the server may not survive a long sleep. Click Reload to restart it
• Server crash — rare, but handled by automatic recovery. If auto-recovery fails, click Reload
• Resource conflict — another process may have taken port 3000

The Reload button triggers a full recovery: health check → restart → wait for healthy → retry.

Port 3000 Conflicts

”Port in use” / EADDRINUSE Error

Another application is using port 3000. Common culprits:

• Another Express/Node.js development server
• React development servers (Create React App defaults to 3000)
• Other CEP extensions with local backends

To fix:

1. Find what is using port 3000:

   lsof -i :3000

2. Stop the conflicting process, or change its port
3. Reload the modelBridge panel

modelBridge cannot currently be configured to use a different port.

Node.js Requirements

The local server requires Node.js to be installed on your machine. modelBridge looks for Node.js in these locations:

• /opt/homebrew/bin/node (Homebrew on Apple Silicon)
• /usr/local/bin/node (Homebrew on Intel Macs)
• System PATH

Checking Node.js

Open Terminal and run:

node --version

If Node.js is not found, install it:

• Homebrew: brew install node
• Direct download: nodejs.org

Any current LTS or stable version of Node.js should work.

Server Dependencies

The backend requires npm packages to be installed. If the server fails to start with module errors:

cd ~/Library/Application\ Support/Adobe/CEP/extensions/com.fittoframe/node
npm install

fal.ai Connectivity

Timeout Errors

“Search timed out” or “Generation timed out” usually means:

• Slow internet connection — fal.ai’s API requires a reliable connection for media uploads and result downloads
• fal.ai is temporarily overloaded — try again in a moment
• Large file upload — uploading high-resolution video can take time on slower connections

The plugin retries automatically up to 3 times with increasing delays (1s, 2s, 4s) before showing an error.

”fal.ai is temporarily unavailable”

fal.ai’s infrastructure is experiencing issues. This is typically transient. The error banner shows a Try again button. If the issue persists, check fal.ai’s status page.

SSL/Certificate Errors

If you are behind a corporate proxy or VPN that intercepts HTTPS traffic, connections to fal.ai may fail with SSL errors. Consult your IT department about adding fal.ai to the proxy allowlist.

API Key Problems

”Invalid API Key”

• Check for extra spaces when copying the key
• Verify the key is active on fal.ai/dashboard/keys
• Generate a new key if the old one was revoked
• Make sure you are using a fal.ai key (not a key from another service)

“Balance exhausted”

Your fal.ai account has no remaining funds. Add credits at fal.ai/dashboard/billing. After topping up, modelBridge detects the restored balance on the next generation attempt.

”Access denied” on specific models

Some models require approval from the creator or a specific API key scope. This is a fal.ai restriction, not a modelBridge issue. The error dialog explains the restriction type and links to where you can request access.

After receiving access, either:

• Save a new API key in the Settings tab (clears the denial cache and rechecks all models)
• Wait 24 hours for the denial cache to expire

Debug Tools

For advanced troubleshooting, open Chrome DevTools at localhost:8089 while the panel is running:

• Console logs — detailed server communication, schema loading, and error normalization
• window.__mb_error_debug() — inspect the last fal.ai error
• window._mbDevMode = true — enables debug info buttons on error banners
• CEP logs — /Library/Logs/CSXS/csxs11-PPRO.log for extension lifecycle events