Error Reference

Every error modelBridge can show, organized by category. Click an error to jump to its section, or use Ctrl+F to search.

Network & Connectivity

Local Server Down

“Cannot connect to the modelBridge backend server.”

Category: critical

What happened: modelBridge’s local helper server is not running or cannot be reached. This server handles media extraction, file uploads, and result downloads. Without it, the plugin cannot function.

Why this happens: The server process crashed or wasn’t started when the panel opened. A firewall or security tool (Little Snitch, macOS Firewall) may be blocking localhost on port 3000. If another app is using port 3000, see Port Conflict.

This is a local issue — your fal.ai account is not affected.

What to do:

Close and reopen the modelBridge panel (Window > Extensions > modelBridge)
If that fails, fully quit and reopen Premiere Pro
Check that no firewall is blocking localhost on port 3000
Run lsof -i :3000 in Terminal to check for port conflicts

Were you charged? No. No request was sent to fal.ai.

Should I retry? Yes, after restarting the panel or Premiere Pro.

How to prevent this: Avoid force-quitting Premiere Pro. Stop dev tools on port 3000 before opening modelBridge.

Network Error

“Could not connect to fal.ai.”

Category: NETWORK_RETRY

What happened: The connection to fal.ai failed. No generation was attempted and no charge applies.

Why this happens: Your internet connection is down or unstable. A corporate proxy, firewall, or VPN may be blocking connections to fal.ai. fal.ai itself may be experiencing an outage.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Open fal.ai/dashboard in your browser to verify connectivity
If that page doesn’t load, check your Wi-Fi, ethernet, or VPN
If fal.ai loads in browser but the plugin fails, a firewall may be blocking background processes
Try again in a moment — brief outages usually resolve within seconds

Were you charged? No. The request never reached fal.ai.

Should I retry? Yes. Network errors are usually temporary.

External resources: fal.ai Status

API Timeout

“The generation timed out.”

Category: NETWORK_RETRY

What happened: The model accepted your request but took too long to complete. fal.ai cancelled it after hitting the processing time limit.

Why this happens: Long duration or high resolution pushed the model close to its time limit. A cold start (model loading into GPU memory) consumed part of the timeout window. Peak usage hours slow individual generations.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Try again immediately — the first attempt may have triggered a cold start
Reduce duration (try 5s instead of 10s)
Lower resolution if available
Try a faster variant (“standard” instead of “pro”)

Were you charged? Usually no. If the model timed out before producing output, no charge applies. Check your fal.ai Dashboard if unsure.

Should I retry? Yes. The second attempt often succeeds because the model is now warm.

How to prevent this: Start with shorter durations and lower resolutions. “Standard” or “turbo” variants are faster than “pro” or “quality.”

External resources: fal.ai Status

Server Error

“fal.ai experienced an internal error.”

Category: NETWORK_RETRY

What happened: fal.ai’s servers encountered an internal error while processing your request.

Why this happens: A temporary infrastructure issue on fal.ai — a GPU worker crashed, a deployment caused instability, or a specific model’s backend is having problems. Usually temporary.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Try again in 30–60 seconds
If it persists on one model, try a different model to confirm it’s model-specific
Check fal.ai Status for known outages

Were you charged? No. The generation did not complete.

Should I retry? Yes. Wait 30–60 seconds.

External resources: fal.ai Status

External Service Error

“A third-party service this model depends on returned an error.”

Category: NETWORK_RETRY

What happened: This model depends on an external API (face detection, voice synthesis, etc.) that failed.

Why this happens: The third-party service is experiencing a temporary outage or network issue. This is outside both modelBridge’s and fal.ai’s control.

This is a model-side issue, not a plugin or account problem.

What to do:

Wait a few minutes and try again
If it persists after 5–10 minutes, try a different model
Check fal.ai Status for known issues

Were you charged? No. The generation did not complete.

Should I retry? Yes, after waiting a few minutes.

External resources: fal.ai Status

Rate Limited

“Too many requests — please wait a moment.”

Category: NETWORK_RETRY

What happened: fal.ai temporarily blocked your request because you exceeded the rate limit. No processing began and no charge applies.

Why this happens: You clicked Generate multiple times in quick succession, or you have too many concurrent generations (including background ones). Some fal.ai account tiers have lower concurrency limits.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Wait 30–60 seconds and try again
Avoid clicking Generate multiple times rapidly
Wait for background generations to complete before starting new ones

Were you charged? No. The request was rejected before processing.

Should I retry? Yes, after waiting 30–60 seconds.

How to prevent this: Click Generate once and wait. Use background generation for multiple outputs.

External resources: fal.ai Status

Port Conflict

“The backend server could not start.”

Category: critical

What happened: Another application is already using port 3000, so modelBridge’s backend server cannot start.

Why this happens: Port 3000 is a common default for web development tools. A previous modelBridge session may have left an orphaned Node.js process.

This is a local issue — your fal.ai account is not affected.

What to do:

Run lsof -i :3000 in Terminal to identify the process
Stop the conflicting application, or kill it: kill -9 <PID>
Reopen the modelBridge panel

Common conflict	How to fix
Create React App	Stop with Ctrl+C, or `PORT=3001 npm start`
Next.js dev server	Stop with Ctrl+C, or `next dev -p 3001`
Express/Node.js server	Stop in its terminal or kill its process
Docker container	`docker ps` then `docker stop <container_id>`
Previous modelBridge	Kill the orphaned `node` process with `kill -9 <PID>`

Were you charged? No. No request was sent to fal.ai.

Should I retry? Yes, after freeing port 3000.

How to prevent this: Stop dev servers on port 3000 before opening modelBridge.

Node.js Not Found

“Could not find Node.js on your system.”

Category: critical

What happened: modelBridge uses a small local server to process your generations and communicate with fal.ai. This server needs Node.js to run, and Node.js was not found on your computer.

Why this happens: Node.js is a free program that modelBridge depends on. It is not included with Premiere Pro or modelBridge and needs to be installed separately. This is a one-time setup step — once installed, you won’t need to do this again.

This is a local issue — your fal.ai account is not affected.

What to do:

Go to nodejs.org and download the LTS version (recommended)
Run the installer and follow the on-screen instructions
Restart Premiere Pro completely after installation — this is required for modelBridge to detect Node.js
If modelBridge still shows this error after restarting, Node.js may not have been added to your system PATH during installation. On macOS this is typically automatic. Try opening Terminal and running node --version — if it prints a version number, Node.js is installed correctly
If the problem persists, contact support

Were you charged? No. No connection to fal.ai was attempted.

Should I retry? Yes, after installing Node.js and restarting Premiere Pro.

Server Binary Could Not Be Launched

“modelBridge’s server binary could not be launched.”

Category: critical

What happened: modelBridge ships with a bundled helper server, and it could not be started. Without this server, the plugin cannot extract media, upload files, or download results.

Why this happens: The installation is incomplete or corrupted — an interrupted install, macOS quarantine flags on the binary, or an antivirus tool that quarantined it.

This is a local issue — your fal.ai account is not affected.

What to do:

Reinstall modelBridge from the installer
Fully quit Premiere Pro (Cmd+Q) and reopen
If an antivirus tool is running, check its quarantine log for modelBridge files
If the problem persists, contact support

Were you charged? No. No connection to fal.ai was attempted.

Should I retry? Yes, after reinstalling and restarting Premiere Pro.

Model Cold Start

“The model took too long to start.”

Category: NETWORK_RETRY

What happened: The model needed to load into GPU memory and timed out before processing could begin.

Why this happens: Popular models stay warm (pre-loaded); less-used models need a cold start that can take 10 seconds to several minutes. Your first request likely triggered the loading process.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Try again immediately — the model is likely still loading from your first attempt
If it fails again, wait 1–2 minutes and retry
Try a more popular variant of the same model family

Were you charged? No. The model never started processing.

Should I retry? Yes — immediately. Your first attempt warms up the model.

How to prevent this: Popular models rarely cold start. For less common models, run a quick cheap generation first to warm them up.

Authentication & Billing

Invalid API Key

“Your fal.ai API key is invalid or missing.”

Category: CREDITS_BILLING (persistent)

What happened: modelBridge could not authenticate with fal.ai. Without a valid API key, no operations are possible.

Why this happens: No key has been entered yet, the key was revoked or regenerated in the fal.ai dashboard, or the key was copied with extra whitespace or missing characters.

This is an account-level issue on fal.ai.

What to do:

Open Settings tab in modelBridge
Delete the current key entirely
Copy a fresh key from fal.ai API Keys
Paste it — no extra spaces before or after
Click Save

Were you charged? No. Authentication failed before any generation.

Should I retry? Only after entering a valid API key.

How to prevent this: Don’t regenerate your fal.ai key unnecessarily. If you do, update it in modelBridge’s Settings tab.

External resources: fal.ai API Keys

Balance Empty

“Your fal.ai balance is empty.”

Category: CREDITS_BILLING (persistent)

What happened: Your fal.ai account balance is too low for this generation. fal.ai uses prepaid credits — when the balance runs out, all generations are blocked.

Why this happens: Previous generations consumed your balance. Video generation at high resolutions with audio can cost several dollars per generation. Your payment method may have failed if auto-top-up was configured.

This is an account-level issue on fal.ai.

What to do:

Add funds at fal.ai billing
Check the cost estimate next to Generate before retrying
To reduce costs: shorter duration, lower resolution, disable audio, use “standard” variants

Were you charged? No. The balance check failed before generation started.

Should I retry? Only after adding funds.

How to prevent this: Check cost estimates before generating. Enable auto-recharge in fal.ai billing settings.

External resources: fal.ai Billing

Insufficient Scope

“Your API key does not have the required permissions.”

Category: CREDITS_BILLING (persistent)

What happened: Your fal.ai API key is valid but lacks the permissions needed. API keys can be created with restricted scopes.

Why this happens: The key was generated with limited permissions, or a team admin restricted certain operations on your organization’s keys.

This is an account-level issue on fal.ai.

What to do:

Generate a new key with full permissions at fal.ai API Keys
Replace the key in modelBridge’s Settings tab
If using a team key, ask your admin for broader permissions

Were you charged? No. The permission check failed before generation.

Should I retry? Only after replacing the key.

How to prevent this: Enable all permission scopes when creating API keys unless you have a specific reason to restrict them.

External resources: fal.ai API Keys

Model Access Gated

“You do not have access to this model.”

Category: critical

What happened: This model requires explicit approval before you can use it. Your API key and account are fine — the restriction is on the model itself.

Why this happens: The model author gated access for beta testing, licensing, or usage agreement reasons. The model appears in search but generation is blocked until approved.

This is a model-side issue, not a plugin or account problem.

What to do:

Visit the model’s page on fal.ai and look for “Request Access”
Check your fal.ai Dashboard for pending access requests
Use an alternative model with similar capabilities

Were you charged? No. The access check failed before generation.

Should I retry? Not until you’ve been granted access.

External resources: fal.ai Dashboard

License Invalid

“Your modelBridge subscription could not be verified.”

Category: CREDITS_BILLING

What happened: modelBridge could not verify your subscription license.

Why this happens: Your subscription expired or your payment method failed during renewal. A temporary network issue may be preventing the license server from being reached. This is separate from your fal.ai API key.

What to do:

Check your modelBridge subscription status
Verify your internet connection
Restart Premiere Pro to trigger a fresh license check

Were you charged? No. License verification doesn’t involve fal.ai.

Should I retry? Yes, if your subscription is active. Restart Premiere Pro.

How to prevent this: Keep your subscription payment method up to date.

License Device Limit

“Maximum devices reached.”

Category: CREDITS_BILLING

What happened: Your modelBridge license has reached the maximum number of activated devices. Each license allows a limited number of simultaneous activations.

Why this happens: You activated modelBridge on more devices than your license allows. This is a license management limit, not a technical error.

What to do:

Open the API & Support tab in modelBridge and click Use on a different device to release the current device
Or manage your devices at app.lemonsqueezy.com/my-orders
After releasing a device, enter your license key again to activate

Were you charged? No. This is a license activation issue.

Should I retry? Yes, after releasing a device from your account.

External resources: Manage Devices

Input & Media

No Media Selected

“No clip or media selected.”

Category: info

What happened: This model requires media input, but nothing is selected in Premiere Pro.

Why this happens: No clip was clicked before clicking Generate, or the selection was lost by clicking an empty area, switching panels, or using keyboard shortcuts. Text-to-video and text-to-image models don’t require media selection.

What to do:

Click a clip in the timeline or project panel
Confirm it’s highlighted when you click Generate
Single-click to select (don’t double-click, which opens Source Monitor)

Were you charged? No. No request was sent to fal.ai.

Should I retry? Yes, after selecting a clip.

How to prevent this: Check the media card in modelBridge — if it shows “No media selected,” click a clip first.

Extract Failed

“Could not extract the selected media from Premiere Pro.”

Category: warning

What happened: A clip was selected but modelBridge could not extract it. This happens locally, before any network request.

Why this happens: The selection was lost between clicking Generate and extraction starting. You may have selected a sequence instead of an individual clip. The source file may be offline (moved, renamed, or on a disconnected drive) or locked by another process.

This is a local issue — your fal.ai account is not affected.

What to do:

Select a single clip, not a sequence or folder
Right-click > “Reveal in Finder” to verify the source file exists
Ensure external drives are connected
Wait for other Adobe apps (Media Encoder) to finish using the file

Were you charged? No. Extraction happens locally before any API call.

Should I retry? Yes. Re-select the clip and try again.

Upload Failed

“Could not upload your media to fal.ai.”

Category: warning

What happened: Media was extracted from Premiere Pro but the upload to fal.ai failed.

Why this happens: Unstable internet connection during transfer. Large files (high-bitrate video, uncompressed images) take longer and are more susceptible. fal.ai’s upload endpoint may be temporarily unavailable.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Check your internet connection
Try again — upload failures often succeed on retry
For large files: use a shorter clip or re-export as JPEG instead of PNG/TIFF
Try a wired connection instead of Wi-Fi

Were you charged? No. The upload failed before generation started.

Should I retry? Yes, immediately.

Content Flagged

“Your input was flagged by content moderation.”

Category: CONTENT_POLICY

What happened: fal.ai’s content moderation blocked your input (prompt or media). modelBridge does not perform content filtering — this is entirely on fal.ai’s side.

Why this happens: Automated moderation flagged words or visual content. False positives occur — medical terminology, historical references, or action-movie descriptions can trigger filters in legitimate contexts.

What to do:

Rephrase your prompt with alternative terms
Try a different source image, or crop potentially flagged content
Try a different model — moderation thresholds vary
Report false positives to fal.ai support

Were you charged? No. Blocked before processing.

Should I retry? Not with the same input. Change prompt or media first.

No Output Generated

“The model could not generate output from your input.”

Category: CONTENT_POLICY

What happened: The model ran but produced no usable output. Unlike a content violation, the model wasn’t blocked — it simply couldn’t create anything from your input and settings.

Why this happens: The input lacked enough information — very dark images, vague prompts, or extreme parameter values. Some models perform secondary content checks during generation and suppress borderline output silently.

What to do:

Try a more specific, descriptive prompt
Use a source image with more detail and contrast
Use moderate settings: guidance scale 7–12, standard aspect ratio, mid-range duration
Try a different model

Were you charged? Possibly. GPU time was consumed. Check your fal.ai Dashboard.

Should I retry? Yes, but change something first — prompt, image, or settings.

Results & Import

Download Failed

“Could not download the generated result.”

Category: warning

What happened: The generation completed on fal.ai but modelBridge could not download the result. The output may still be available.

Why this happens: Network interruption during download. The result URL may have expired due to a long delay between generation and download. fal.ai’s file storage may be temporarily unavailable.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Try generating again — cached results download instantly at no charge
Check your internet connection
Check your fal.ai Dashboard for direct download

Were you charged? Possibly. The generation completed, so compute cost was incurred. Cached retries are free.

Should I retry? Yes. Cached results are instant and free.

Import Timeout

“Premiere Pro took too long to import the file.”

Category: warning

What happened: The file was downloaded but Premiere Pro didn’t complete the import in time. The file exists on disk and can be imported manually.

Why this happens: Premiere Pro is busy with another operation (rendering, exporting, conforming audio). Low system resources can also slow imports.

This is a local issue — your fal.ai account is not affected.

What to do:

Import manually: File > Import from modelBridge’s downloads folder
Wait for Premiere Pro to finish any background tasks
Restart Premiere Pro if this happens frequently

Were you charged? Yes — the generation completed and the file is saved locally.

Should I retry? No need to regenerate. Import the file manually.

Import Failed

“Premiere Pro could not import the generated file.”

Category: warning

What happened: The file was downloaded but Premiere Pro rejected it — unsupported format, corrupted file, or missing codec.

Why this happens: Some models output WebM, AVI, or other formats Premiere doesn’t support natively. The download may have been corrupted. Some models produce files with unusual metadata.

This is a local issue — your fal.ai account is not affected.

What to do:

Open the file in VLC to verify it’s playable
If it plays in VLC, convert to H.264 MP4: ffmpeg -i input.webm -c:v libx264 output.mp4
If it doesn’t play anywhere, regenerate
Try a different model that outputs H.264 MP4

Were you charged? Yes — the generation completed. The file can be converted and imported manually.

Should I retry? Only if the file is corrupted. Otherwise, convert it.

Model & Schema

Model Not Found

“This model is no longer available on fal.ai.”

Category: warning

What happened: The model endpoint does not exist on fal.ai. It may have been removed, renamed, or replaced.

Why this happens: The model was updated to a new version with a different endpoint (e.g., /v2 replaced by /v3). Model authors sometimes rename, consolidate, or remove endpoints.

What to do:

Search for the model by name in modelBridge — it may have a new endpoint
Remove the missing model and add the updated version
Visit fal.ai/models to check the model’s current status

Were you charged? No. The endpoint doesn’t exist, so nothing was attempted.

Should I retry? Not with the same model. Find the updated endpoint.

External resources: fal.ai Models

Schema Failed

“Could not load this model’s configuration.”

Category: warning

What happened: modelBridge could not load the model’s API schema from fal.ai. Without it, the settings UI cannot be built and generation requests cannot be constructed.

Why this happens: A temporary issue with fal.ai’s schema endpoint. A newly published model’s schema may not be available yet. The model may use a schema format modelBridge doesn’t support.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Wait a moment and try selecting the model again
Remove and re-add the model for a fresh schema fetch
Check your internet connection

Were you charged? No. Schema loading happens before any generation.

Should I retry? Yes. Schema issues are usually temporary.

Generation

Queue Failed

“Could not submit the generation request.”

Category: warning

What happened: Media was uploaded and settings were validated, but the final queue submission failed. No generation was started.

Why this happens: A network interruption at the moment of submission. fal.ai’s queue system may be experiencing issues or temporarily not accepting new requests.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Try again immediately — queue failures are almost always transient
Check your internet connection
Check fal.ai Status

Were you charged? No. The request never entered the queue.

Should I retry? Yes, immediately.

External resources: fal.ai Status

No Media in Result

“Generation completed but no media file was returned.”

Category: warning

What happened: fal.ai reported success but the response didn’t contain a downloadable media URL.

Why this happens: fal.ai’s response was incomplete — the generation succeeded on GPU but the result wasn’t properly linked. The model may return results in a non-standard format modelBridge can’t parse.

This is a model-side issue, not a plugin or account problem.

What to do:

Try generating again — often a one-time glitch
Check your fal.ai Dashboard — the result may be downloadable there
Try a different model if it persists

Were you charged? Possibly. The generation ran on fal.ai’s GPU. Check your dashboard.

Should I retry? Yes. Usually a one-time issue.

External resources: fal.ai Dashboard

Mask Duration

“The mask video is too short for this model.”

Category: warning

What happened: Your inpainting mask is a still image or a video shorter than the model’s minimum duration. Inpainting masks must be video clips matching the input duration.

Why this happens: A single mask frame was provided instead of a video mask. The mask video is shorter than the input clip.

Caught before generation — no API call was made, no charge.

What to do:

Use modelBridge’s built-in Draw Mask tool — it creates masks at the correct duration automatically
If creating masks externally, ensure it’s a video file matching or exceeding the input clip duration
Check the model’s minimum mask duration in settings

Were you charged? No. Pre-flight validation.

Should I retry? Yes, after providing a proper video mask.

Validation Error

“A required setting is missing or invalid.”

Category: warning

What happened: One or more parameters are missing, empty, or outside the model’s accepted range.

Why this happens: A required field (like prompt) is blank. A parameter value is outside the allowed range. Some parameter combinations are invalid (e.g., audio + unsupported resolution).

Caught before generation — no API call was made, no charge.

What to do:

Check highlighted fields above the Generate button — errors are shown inline
Fill in empty required fields
Adjust out-of-range values to match the limits shown in the error
Check the model’s fal.ai page if unsure about valid values

Were you charged? No. Validation happens locally.

Should I retry? Yes, after fixing the highlighted fields. Generate enables automatically once all fields are valid.

GPU Memory Exceeded

“The model ran out of GPU memory.”

Category: NETWORK_RETRY

What happened: The GPU worker ran out of VRAM while processing your generation.

Why this happens: High resolution + long duration exceeded the GPU’s available memory. fal.ai may have assigned a worker with insufficient memory for this combination of settings.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Try again — fal.ai may assign a different GPU with more memory
Reduce resolution (720p instead of 1080p)
Reduce duration
Try a “standard” or “lite” model variant

Were you charged? No. The generation failed before completing.

Should I retry? Yes. GPU allocation varies between attempts.

External resources: fal.ai Status

Invalid LoRA URL

“The provided LoRA URL could not be resolved.”

Category: INPUT_QUALITY

What happened: The model tried to load a LoRA weight file from a URL that could not be resolved or downloaded.

Why this happens: The URL is incorrect, the file was moved or deleted, or the hosting service requires authentication. If you didn’t provide a LoRA URL, the model uses a built-in LoRA that’s temporarily unavailable.

What to do:

Open the URL in a private/incognito browser to verify it’s publicly accessible
Ensure the URL points to a file (.safetensors or .bin), not a webpage
Try removing the LoRA URL and generating without it
For built-in LoRAs: wait a few minutes and retry

Were you charged? No. Error occurs before generation starts.

Should I retry? After verifying or replacing the URL. For built-in LoRAs, try again in a few minutes.

Speaker Not Found

“The specified speaker ID was not recognized.”

Category: INPUT_QUALITY

What happened: The speaker ID set for this audio/speech model is not recognized.

Why this happens: The model’s available speakers changed since the schema was cached, the ID has a typo, or the speaker was removed in a newer model version.

What to do:

Select a different voice from the speaker dropdown
Leave the field empty to use the model’s default voice
Remove and re-add the model to refresh the speaker list

Were you charged? No. Error occurs before generation starts.

Should I retry? Yes, after selecting a valid speaker or using the default.

Feature Not Supported

“Option not available”

Category: warning

What happened: A setting is listed in the model’s schema but isn’t functional on fal.ai’s backend.

Why this happens: The model author published the schema before implementing the feature, or the feature was deprecated. It may only work with specific parameter combinations.

What to do:

Disable or change the setting that triggered the error
Use default values — defaults are always supported
Check the model’s fal.ai page for feature requirements

Were you charged? No. Caught during parameter validation.

Should I retry? Yes, after changing or disabling the unsupported setting.

File Could Not Be Loaded

“File could not be loaded”

Category: warning

What happened: You provided a URL for an external file, and fal.ai’s servers could not download or read it.

Why this happens: The URL requires authentication — fal.ai makes a direct HTTP request and can’t log in. The file was moved or deleted. URL redirects may prevent fal.ai from reaching the actual file.

What to do:

Open the URL in a private/incognito browser — if you can’t access it logged out, fal.ai can’t either
Ensure the URL points directly to a file, not a webpage
For private files (Google Drive, Dropbox), set sharing to “Anyone with the link”

Were you charged? No. Error occurs during input processing.

Should I retry? Only after fixing the URL.

How to prevent this: Test URLs in private/incognito before entering them. Use direct file links from public hosting.

Parameter Constraint Errors

“Value too low” / “Value too high” / “Invalid value” / “Too few items” / “Too many items”

Category: warning

What happened: A parameter value is outside the range this model accepts. The exact constraint is in the error message.

Why this happens: Each model has its own valid ranges. Width/height often must be multiples of 8 or 16. Guidance scale ranges vary between models. List parameters have item count limits.

Caught before generation — no API call was made, no charge.

What to do:

Read the error message for the exact constraint
Adjust the value to the allowed range
For multiple constraints (e.g., “must be a multiple of 8”), round to the nearest valid value
For list constraints, add or remove items as indicated

Were you charged? No. Validation happens locally.

Should I retry? Yes, after adjusting the value. The error clears automatically once valid.

Input & Media Validation

modelBridge checks your media before sending it to fal.ai. If a check fails, the media card turns red and Generate is disabled. The same pre-flight system also checks the model’s settings — required fields, value ranges, and dropdown options. You are never charged for a pre-flight validation failure.

When modelBridge learns a new constraint from a failed generation, it saves it permanently. Next time, pre-flight catches it instantly — no API call, no charge.

Image Too Small

“Image too small”

What happened: Your image’s pixel dimensions are below this model’s minimum. The error shows actual vs. required dimensions.

Why this happens: Small thumbnails, web-optimized images, proxy files, or screenshots fall below model minimums (typically 256x256 to 1024x1024). This may be a learned constraint from a previous failed generation.

Caught before generation — no API call was made, no charge.

What to do:

Check the error for exact minimum dimensions
Export a full-resolution frame: File > Export Frame > JPEG
If using proxy media, switch to full-resolution first
Choose a model with lower minimum requirements

Were you charged? No.

Should I retry? Yes, after providing a larger image.

Image Too Large

“Image too large”

What happened: Your image exceeds the maximum dimensions this model supports. The error shows actual vs. allowed dimensions.

Why this happens: RAW or high-resolution photography, panoramic images, or stitched photos exceed model maximums (typically 2048x2048 to 4096x4096).

Caught before generation — no API call was made, no charge.

What to do:

Check the error for exact maximum dimensions
Export at sequence resolution: File > Export Frame (typically 1920x1080 or 3840x2160)
Crop panoramic images to a standard aspect ratio first

Were you charged? No.

Should I retry? Yes, after resizing or cropping.

Video Too Short

“Video too short”

What happened: Your clip is shorter than this model’s minimum duration. The error shows actual vs. required duration.

Why this happens: The clip was trimmed too aggressively, or it’s a freeze frame saved as a very short video. Minimums are typically 1–5 seconds.

Caught before generation — no API call was made, no charge.

What to do:

Extend the clip’s in/out points on the timeline
Slow the clip down (right-click > Speed/Duration) if the source is too short
For single frames, use an image-to-video model instead

Were you charged? No.

Should I retry? Yes, after using a longer clip.

Video Too Long

“Video too long”

What happened: Your clip exceeds this model’s maximum duration. The error shows actual vs. allowed duration.

Why this happens: Each model has a hard limit on processing duration (varies from 5 to 30 seconds). Longer clips multiply GPU computation and cost.

Caught before generation — no API call was made, no charge.

What to do:

Trim the clip on the timeline to fit within the limit
Process in segments: trim, generate each separately, reassemble
Check if a “pro” or “extended” variant supports longer durations

Were you charged? No.

Should I retry? Yes, after trimming.

File Too Large

“File too large”

What happened: The file size exceeds this model’s upload limit. The error shows actual vs. maximum size.

Why this happens: High-bitrate footage (ProRes, DNxHR, uncompressed) can be extremely large. Defaults are 10 MB for images, 500 MB for video, but models may set lower limits.

Caught before generation — no API call was made, no charge.

What to do:

For video: export as H.264 MP4 (much smaller than ProRes)
For images: re-export as JPEG at 80–90% quality via File > Export Frame
Use a shorter clip or lower resolution

Were you charged? No.

Should I retry? Yes, after reducing file size.

How to prevent this: Use H.264 MP4 for video and JPEG for images. AI models resize input internally — ProRes quality isn’t needed.

Unsupported Format

“Unsupported format”

What happened: This model doesn’t accept your file’s format. The error lists supported formats.

Why this happens: Professional formats (ProRes, MXF, CinemaDNG, PSD, EXR) aren’t supported by most AI models. Most accept JPEG/PNG for images, H.264 MP4 for video, WAV/MP3 for audio.

Caught before generation — no API call was made, no charge.

What to do:

For images: File > Export Frame > JPEG or PNG
For video: File > Export > Media > H.264
For audio: export as WAV or MP3

Were you charged? No.

Should I retry? Yes, after converting to a supported format.

Invalid Aspect Ratio

“Unsupported aspect ratio”

What happened: Your media’s aspect ratio is outside this model’s supported range.

Why this happens: Ultra-wide (21:9), ultra-tall (1:3), or unusual aspect ratios from cropping fall outside supported ranges. Most models support 16:9, 9:16, 1:1, and 4:3.

Caught before generation — no API call was made, no charge.

What to do:

Crop or resize to a supported ratio
Safe defaults: 16:9 (1920x1080), 9:16 (1080x1920), 1:1 (1080x1080), 4:3 (1440x1080)

Were you charged? No.

Should I retry? Yes, after adjusting the aspect ratio.

Invalid Image

“Invalid image format”

What happened: The model received your image but could not decode it. The extension may be correct (.jpg) but the actual content is problematic.

Why this happens: Corrupted file, CMYK JPEG, 16-bit PNG, progressive JPEG with unusual encoding, or mismatched extension (WebP renamed to .jpg).

What to do:

Verify the image opens in another app (Preview, Photoshop, browser)
Re-export as standard sRGB JPEG or 8-bit PNG: File > Export Frame
If the image doesn’t open anywhere, it’s corrupted — use a different source

Were you charged? No. Caught during input processing.

Should I retry? Yes, after re-exporting or replacing the image.

Audio Too Long

“Audio too long”

What happened: Your audio clip exceeds this model’s maximum duration. The error shows actual vs. allowed duration.

Why this happens: Audio models have duration limits — voice models typically 10–30 seconds, music models longer but still capped.

Caught before generation — no API call was made, no charge.

What to do:

Trim the audio to fit the limit (Razor tool or adjust in/out points)
Split into segments and process separately
Export just the needed portion as a separate file

Were you charged? No.

Should I retry? Yes, after trimming.

Audio Too Short

“Audio too short”

What happened: Your audio clip is shorter than this model’s minimum. The error shows actual vs. required duration.

Why this happens: Voice cloning needs at least 3–5 seconds of clear speech. Music models need enough context to understand the style. Short clips or sound effects don’t contain enough information.

Caught before generation — no API call was made, no charge.

What to do:

Use a longer clip with clear, uninterrupted content
For voice cloning: at least 5 seconds of clear speech, no background noise
For music: use a longer excerpt capturing the musical style

Were you charged? No.

Should I retry? Yes, after providing a longer clip.

No Face Detected

“No face detected”

What happened: This model requires a visible human face but the detection algorithm couldn’t find one.

Why this happens: The face is too small in the frame, obscured (sunglasses, masks, hair), at an extreme angle, poorly lit, motion-blurred, or the image contains multiple faces when the model expects one.

What to do:

Use a well-lit, forward-facing portrait where the face fills at least 20–30% of the frame
Avoid sunglasses, masks, and heavy obstructions
For group photos, crop to a single person

Were you charged? No. Caught before generation starts.

Should I retry? Yes, with a clearer face photo.

How to prevent this: Passport-style photos (neutral expression, facing camera, even lighting) work most reliably.

Image Could Not Be Loaded

“Image could not be loaded”

What happened: fal.ai received your image but could not process it. The file arrived but was unreadable at the infrastructure level.

Why this happens: The image was corrupted during upload. Uncommon image variants (animated PNG, Lab color space, large embedded metadata) can cause failures. URL-provided images may require authentication or redirect through pages fal.ai can’t follow.

This is on fal.ai’s side — your input and settings are fine.

What to do:

Re-export from Premiere Pro: File > Export Frame (produces clean sRGB JPEG/PNG)
If using a URL, verify it downloads the actual image in a private browser
Try a different source image

Were you charged? No. Error occurs during input processing.

Should I retry? Yes, after re-exporting or replacing the image.

Required Setting Missing

“[Setting] is required”

What happened: A required setting for this model is empty. Every model defines its own required fields — modelBridge reads them from the model’s schema and checks them before anything is sent.

Why this happens: A required field was left blank — often after switching models, since each model requires different settings. Prompt fields are a special case: some models can generate without a prompt, so an empty prompt shows a softer warning (“empty — some models can generate without a prompt”) and lets you generate anyway.

Caught before generation — no API call was made, no charge.

What to do:

Check the highlighted fields above the Generate button — the error names the exact setting
Enter a value for it
For an empty prompt: add one for better results, or generate anyway

Were you charged? No. Validation happens locally.

Should I retry? Yes — Generate enables automatically once the field is filled.

Required Media Missing

“Select a clip from your timeline or project bin”

What happened: This model requires a media input — an image, video, or audio file — that hasn’t been provided yet.

Why this happens: No clip is selected in Premiere Pro, or an auxiliary media field (a mask, an end frame, a reference list) is empty. The message tells you which kind:

Main input: “Select a clip from your timeline or project bin”
Media list: “Add [media] using the upload area”
Auxiliary field: “Upload or paste a URL for [field]”

Caught before generation — no API call was made, no charge.

What to do:

For the main input: click a clip in the timeline or project panel
For media lists: add files using the field’s upload area
For auxiliary fields (mask, end frame): upload a file or paste a URL on that field

Were you charged? No. Validation happens locally.

Should I retry? Yes, after providing the missing media.

Value Out of Range

“too low (minimum X)” / “too high (maximum X)”

What happened: A numeric setting is outside the range this model accepts. The error names the setting and the exact limit.

Why this happens: Each model defines its own valid ranges — a duration or step count that works on one model can be out of range on another. Values often carry over when you switch models.

Caught before generation — no API call was made, no charge.

What to do:

Read the limit in the error message
Adjust the value — “Increase [setting] to at least N” or “Lower [setting] to N or below”

Were you charged? No. Validation happens locally.

Should I retry? Yes — the error clears automatically once the value is in range.

Invalid Dropdown Value

“invalid value” — “Choose from: …”

What happened: A setting holds a value that isn’t one of this model’s accepted options. The error lists valid choices.

Why this happens: The model’s options changed since it was installed, or a saved value from another model carried over. Dropdown options are model-specific.

In dual mode, the second model is handled more leniently: modelBridge automatically picks the closest matching option and shows a warning instead of blocking.

Caught before generation — no API call was made, no charge.

What to do:

Open the dropdown named in the error and pick one of the listed options
If the options look outdated, remove and re-add the model to refresh them

Were you charged? No. Validation happens locally.

Should I retry? Yes, after choosing a valid option.

Type Mismatch

“must be a number”

What happened: A numeric setting contains something that isn’t a number.

Why this happens: Text was typed into a number field — a stray character, a unit (“5s”), or a comma used as a decimal separator.

Caught before generation — no API call was made, no charge.

What to do:

Clear the field named in the error
Enter digits only — use a period for decimals (e.g., 7.5)

Were you charged? No. Validation happens locally.

Should I retry? Yes, after entering a valid number.

Setting Combination Not Allowed

“Provide a value for [setting] or [setting]”

What happened: This model requires at least one of a group of related settings, and none of them is filled in.

Why this happens: Some models accept several alternative inputs — for example, either an uploaded image or a reference URL — and need at least one of them. modelBridge knows these rules and checks them before submitting.

Caught before generation — no API call was made, no charge.

What to do:

Read the error — it lists every setting that can satisfy the requirement
Fill in whichever one fits your workflow — one is enough

Were you charged? No. Validation happens locally.

Should I retry? Yes, after providing one of the listed settings.

Conditionally Required Setting

“required for this configuration”

What happened: A setting that is normally optional became required because of another setting’s current value.

Why this happens: Some model settings depend on each other — enabling one feature can make another field mandatory. modelBridge reads these dependencies from the model’s schema and enforces them as soon as your configuration triggers them.

Caught before generation — no API call was made, no charge.

What to do:

Fill in the field named in the error
Or change the setting that triggered the requirement — the field becomes optional again

Were you charged? No. Validation happens locally.

Should I retry? Yes, after filling the field or changing the configuration.

Dual Mode: Missing Input

“required by this model”

What happened: In dual mode, the second model is missing a required setting. Both models are validated independently against their own requirements before anything is sent.

Why this happens: The two models have different requirements — a setting that’s optional on your primary model can be required on the secondary one. The source clip itself is shared automatically between both models, so this is about the other settings.

Caught before generation — no API call was made, no charge.

What to do:

Open the second model’s settings in the dual mode panel
Fill in the field named in the error

Were you charged? No. Neither model was submitted.

Should I retry? Yes, after completing the second model’s settings.

Dual Mode: Setting Out of Bounds

“too low (minimum X)” / “too high (maximum X)”

What happened: In dual mode, one of the second model’s settings is outside the range that model accepts.

Why this happens: Shared settings are adapted to each model’s own limits — numeric values are clamped automatically where possible, and dropdowns snap to the closest valid option. When a value can’t be adapted safely, this error asks you to adjust it manually.

Caught before generation — no API call was made, no charge.

What to do:

Open the second model’s settings in the dual mode panel
Adjust the value named in the error to the limit shown

Were you charged? No. Neither model was submitted.

Should I retry? Yes, after adjusting the value.

Remotely Updated Limit

“too high (max X) — restricted by configuration”

What happened: A setting is blocked by a protective limit that modelBridge received as a remote update — separate from the model’s own schema.

Why this happens: When a model misbehaves in the field — a specific value crashes it, or an option silently produces broken output — modelBridge can ship a protective limit to all users within an hour, without a plugin update. These limits only ever tighten what a model accepts, never loosen it. The message may include a specific reason.

Caught before generation — no API call was made, no charge.

What to do:

Adjust the value to the limit shown, or choose a different option
These limits protect you from a known issue — they’re usually lifted once the underlying model problem is fixed

Were you charged? No. Validation happens locally.

Should I retry? Yes, within the shown limits.

Model Interface Partially Verified

What happened: This model’s full interface couldn’t be verified, so some settings render as plain text inputs instead of specialized controls. modelBridge doesn’t show a banner for this state — you’ll notice it as settings that look like plain text boxes.

Why this happens: The model’s schema was unavailable or incomplete when the model was added, so modelBridge built a basic interface from what it knows about the model’s category. Generation still works — values are passed through as entered.

What to do:

Generate normally — if a value doesn’t fit, the model returns a specific error and modelBridge learns the constraint for next time
Remove and re-add the model to retry loading the full interface

Were you charged? Only for generations you run. The partial interface itself never costs anything.

Should I retry? Yes — this state never blocks generation.

Model Interface Not Recently Verified

“this model’s interface hasn’t been verified in X days”

What happened: This model runs on a hand-tuned interface maintained by modelBridge, and it hasn’t been re-verified against fal.ai in over 90 days. This is a heads-up, not a block.

Why this happens: A small number of models use curated interfaces instead of auto-generated ones. When one hasn’t been checked in a while, the model may have changed on fal.ai’s side in the meantime.

What to do:

Generate normally — this warning never blocks you
If generation fails, the error will be specific, and modelBridge learns from it

Were you charged? Not by this warning. Normal generation charges apply if you proceed.

Should I retry? This is only a notice — proceed as usual.

Integration

Extension Not Loaded

“The modelBridge extension did not initialize.”

Category: critical

What happened: Premiere Pro didn’t load the plugin panel. The extension host, panel code, backend server, or ExtendScript bridge failed to start.

Why this happens: Premiere Pro needs a restart after installing or updating modelBridge. Extension files may be corrupted. On macOS, unsigned extensions must be enabled.

This is a local issue — your fal.ai account is not affected.

What to do:

Fully quit Premiere Pro (Cmd+Q) and reopen
Check Window > Extensions for modelBridge
If not listed, reinstall from the installer

Enable unsigned extensions:

defaults write ~/Library/Preferences/com.adobe.CSXS.11.plist PlayerDebugMode 1

Restart Premiere Pro after running the command
Check CEP log for details: /Library/Logs/CSXS/csxs11-PPRO.log

Were you charged? No. No connection to fal.ai was attempted.

Should I retry? Yes, after restarting Premiere Pro.

Premiere Scripting Error

“A Premiere Pro operation failed.”

Category: warning

What happened: An ExtendScript operation failed during communication with Premiere Pro.

Why this happens: Premiere Pro was busy (rendering, exporting, conforming audio) and the scripting engine timed out. No sequence is open, or the timeline state changed during the operation.

This is a local issue — your fal.ai account is not affected.

What to do:

Ensure a sequence is open in the timeline
Wait for renders/exports to finish
Try the operation again
Reopen the modelBridge panel if it persists
Restart Premiere Pro as a last resort

Were you charged? No. Scripting errors occur locally.

Should I retry? Yes. Wait for Premiere to finish background tasks first.

Storage Full

“Your changes could not be saved — storage is full.”

Category: warning

What happened: modelBridge stores your installed models, generation history, and settings locally on your computer. The available storage space for the extension has been exceeded, so your latest changes could not be saved.

Why this happens: This usually occurs after extended use with many installed models or a long generation history. modelBridge stores data efficiently, but the storage limit can be reached over time.

Your installed models and settings are safe. This error only affects new changes being saved — nothing already stored has been lost.

What to do:

Open the Costs tab in modelBridge and clear old generation history you no longer need
Go to Your AI Models and remove models you don’t use anymore
If the problem persists, close and reopen Premiere Pro — modelBridge automatically cleans up temporary data on restart
If you continue to see this error, contact support

Were you charged? This error does not affect fal.ai billing. Any generation that completed successfully was already saved.

Should I retry? Yes, after freeing up space using the steps above.

Internal Model Update Failed

“Some internal model updates couldn’t be completed. Your installed models are still safe and available.”

Category: warning

What happened: modelBridge occasionally upgrades the internal format of your installed models (for example, to improve pricing data). One of these upgrades could not start safely, so it was cancelled before touching anything.

Why this happens: Before any internal update runs, modelBridge first writes a timestamped backup of your models and rehearses the update on a copy. If the backup can’t be written — usually a full disk — or the rehearsal fails, the real update is aborted and your data is never modified.

This is a local issue — your fal.ai account is not affected, and no data was lost.

What to do:

Close and reopen the modelBridge panel — the update retries automatically
If it keeps happening, check that your disk has free space
Contact support if the issue persists

Were you charged? No. This is internal housekeeping — nothing involves fal.ai.

Should I retry? No action needed — it retries automatically next time the panel opens.

Unknown / Unrecognized

Unknown Error

“Something went wrong.”

Category: DEVELOPER_BUG

What happened: modelBridge encountered an error that doesn’t match any known pattern. This could be a new fal.ai error type, an unusual edge case, or an unexpected response format.

Why this happens: fal.ai evolves continuously — new error types appear as models update. modelBridge’s OTA error update system adds translations for new errors, usually within hours.

What to do:

Try again — many unknown errors are transient
Try different settings or a different model
If it persists, report it:

Were you charged? Depends on when the error occurred. Before generation: no. During generation (progress past “Generating”): possibly. Check your fal.ai Dashboard.

Should I retry? Yes. Unknown errors are often one-time occurrences.

Reporting: With Developer Mode enabled, click the ”?” button on the error banner to copy debug info — include this in your report.

Email: support@modelbridge.app

Keep learning

Errors are one side of the story. For the patterns behind recurring generation problems — smearing, stutter, lipsync drift, anatomy issues — and when to fix them in Premiere instead of regenerating, see Common failure modes — and what to do about them.

Error Reference

Jump to category

Network & Connectivity

Local Server Down

Network Error

API Timeout

Server Error

External Service Error

Rate Limited

Port Conflict

Node.js Not Found

Server Binary Could Not Be Launched

Model Cold Start

Authentication & Billing

Invalid API Key

Balance Empty

Insufficient Scope

Model Access Gated

License Invalid

License Device Limit

Input & Media

No Media Selected

Extract Failed

Upload Failed

Content Flagged

No Output Generated

Results & Import

Download Failed

Import Timeout

Import Failed

Model & Schema

Model Not Found

Schema Failed

Generation

Queue Failed

No Media in Result

Mask Duration

Validation Error

GPU Memory Exceeded

Invalid LoRA URL

Speaker Not Found

Feature Not Supported

File Could Not Be Loaded

Parameter Constraint Errors

Input & Media Validation

Image Too Small

Image Too Large

Video Too Short

Video Too Long

File Too Large

Unsupported Format

Invalid Aspect Ratio

Invalid Image

Audio Too Long

Audio Too Short

No Face Detected

Image Could Not Be Loaded

Required Setting Missing

Required Media Missing

Value Out of Range

Invalid Dropdown Value

Type Mismatch

Setting Combination Not Allowed

Conditionally Required Setting

Dual Mode: Missing Input

Dual Mode: Setting Out of Bounds

Remotely Updated Limit

Model Interface Partially Verified

Model Interface Not Recently Verified

Integration

Extension Not Loaded

Premiere Scripting Error

Storage Full

Internal Model Update Failed

Unknown / Unrecognized

Unknown Error

Keep learning