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 heartbeat monitors server health continuously. If the server becomes unresponsive:

The plugin detects the failure automatically
A restart is triggered within seconds
If recovery succeeds, you see no interruption
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:

Find what is using port 3000:
Terminal window
```
lsof -i :3000
```
Stop the conflicting process, or change its port
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 on your system automatically. If Node.js is installed via Homebrew or the standard installer, it should be found automatically.

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 with increasing delays 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 for the denial cache to expire

Debug Tools

For advanced troubleshooting, open Chrome DevTools while the panel is running (see Adobe’s CEP debugging documentation for setup). The console shows detailed server communication, schema loading, and error normalization. With Developer Mode enabled, error banners include a ”?” button that copies debug info to your clipboard for support tickets.

CEP logs can be found in the standard Adobe log directory for extension lifecycle events.