Troubleshooting

Fixes for common issues across jobs, pipeline stages, AI providers, billing, script generation, visual batches, style imports, narration, and editor timelines.

#Quick symptom-to-fix guide

Use this quick diagnostic table to match what you see on screen to its root cause and immediate fix:

Symptom or error message	Likely cause	How to fix it
Pipeline stage says Blocked or Prerequisite missing	The script is still in `DRAFT` or `REVIEW` status, or an earlier required stage is incomplete.	Open the script in Script Viewer and click Approve Script, then return to Pipeline.
Job stays Queued or Running for a long time	Either workers are processing a large queue or the batch was submitted in Batch (50% off) mode (up to 24h provider turnaround).	For Instant jobs, wait 1–2 minutes or check Jobs. For 50%-off provider batches, open the batch in Visual and click Refresh to poll the provider.
401 Unauthorized or Invalid API key	A custom BYOK API key is expired, revoked, or pasted with extra characters.	Open AI Providers, click Test next to the provider, and update the key or switch the route back to Flow Managed.
429 Too Many Requests or Quota exceeded	Your personal provider account hit its requests-per-minute or monthly spend limit during a batch.	Wait 60 seconds and click Retry from saved state in Jobs, use Batch (50% off) for large image runs, or switch to Flow Managed credits.
Insufficient balance or billable AI features paused	Your prepaid Flow credit balance reached 0 while using managed platform models.	Open Billing and add funds ($10, $25, $50, $100, or custom), or configure your own provider API key in AI Providers.
Automatic pipeline stops at Audio	No voice has been selected in Audio Studio yet.	Open Audio, click Browse voices, and select a voice (Use or the robot icon) from ElevenLabs, MiniMax, Fish Audio, or AI33 Pro.
Characters or locations change appearance between scenes	Scenes or visuals were generated before saving the Creative Bible or its reference sheets.	Complete and save the Creative Bible and generate its sheets first, then generate Images before Videos in Visual.
Gemini Style Import says Invalid JSON or Truncated	Gemini cut off a long JSON response or wrapped it in partial text.	In Import Style from Gemini, click + Add next chunk to paste continuation parts and click Merge chunks & Import.

#A job stays queued, keeps retrying, or fails mid-run

Queued for a long time: background workers may be busy; wait a few minutes. If it never starts, contact support.
Retrying repeatedly: usually a provider or API key problem. Check the job's error in Jobs and your keys in AI providers.
Batch (50% off) vs. Instant: Instant jobs execute immediately on live workers. Batch (50% off) image batches are queued on OpenAI or Gemini's asynchronous batch cluster, which can take from a few minutes up to 24 hours. Open the batch with View on the Visual page and press Refresh to check the provider's live status.
Retry from saved state: When a multi-step job (Script, Outline, Scene Breakdown, Creative Bible, or Pipeline) fails after completing earlier work, open the job in Jobs and click Retry from saved state (or Retry on the job row) so Flow resumes from its saved checkpoint instead of starting from zero.
Paused or Cancelled jobs: If you paused a queued job, click Resume in Jobs to return it to the worker queue.

On the Jobs page, click the Failed summary tile at the top to immediately filter the list to jobs that need your attention, and use Copy Job ID on any job detail page if you need to share it with support.

#Pipeline stages are blocked or automatic run pauses

Script not approved: Every production stage after Script requires an Approved script. Draft (DRAFT) and review (REVIEW) scripts — including scripts newly generated in Bulk Script or restored from Trash Jobs — stay locked until you open them in Script Viewer and click Approve Script.
Wrong script version selected: If a project has multiple script versions, use the production picker bar at the top of the page to make sure the Approved version is selected.
Automatic pipeline stops at Audio: Automatic pipeline narration uses the voice that has been selected in Audio. Open Audio → Browse voices and click Use (or the robot button) on any ElevenLabs, MiniMax, Fish Audio, or AI33 Pro voice (clicking the star only adds it to Favorites).
Scenes waiting for approval: When running manually, Visual only renders scenes marked Ready. In Scenes, click Mark all Ready or Approve Ready before moving to Visual (automatic Pipeline runs approve complete scenes automatically).

#API keys, provider errors, and billing balance

401 Unauthorized / Invalid API Key: Open AI Providers (Settings → AI Providers) and click Test on the provider showing errors. Make sure you pasted the raw key without leading/trailing spaces, or clear the custom key to use Flow Managed credits.
429 Rate Limit / Quota Exceeded: Providers enforce requests-per-minute (RPM) and tokens-per-minute (TPM) limits on personal API keys. If a large scene or image batch hits 429, Flow automatically backs off and retries; if your provider account has $0 credit left on its own dashboard (e.g., OpenAI or Together AI billing), top up that provider account or switch the route to Flow Managed.
Insufficient Flow balance: Billable AI actions pause when your Available Balance reaches 0 credits (unless your account is billing-exempt or using your own API keys). Visit Billing to add funds and set a Low balance alert so you are notified before credits run out.
Checkout completed but balance did not update: Refresh the Billing page and check Recent funding. If a payment shows PENDING, wait 30–60 seconds for the payment webhook to settle and click the refresh button.

#Script generation, outlines, and YouTube research issues

YouTube URL or transcript import fails: Ensure the YouTube video is Public (not Unlisted/Private/Members-only) and has spoken dialogue or captions. Live streams that have not finished processing may not have transcripts available yet.
Script word count is too short or too long: Flow writes the full script chapter by chapter following the word budgets in Script Outline. Before clicking Generate Script, check the chapter list in the outline and adjust individual chapter word targets or click Regenerate Outline.
Bulk Script batch stopped: Open Bulk Script and check if Review outlines before generating full scripts is turned on — when enabled, the batch intentionally pauses at the outline checkpoint until you review and approve the outlines.
Accidentally deleted a script or outline: Open Trash Jobs, toggle Restorable only, and click Restore. Restored scripts return as a new REVIEW version in their original project.

#Visual generation, safety filters, and character consistency

Prompt blocked by safety / content policy: Image and video models reject prompts containing graphic violence, explicit content, real celebrity/politician names, or trademarked logos. Open the failed scene in Scenes or the batch modal in Visual, rephrase the prompt to describe the visual action more neutrally, save, and click Regenerate.
Characters or style look inconsistent across scenes: Always save your Creative Bible and render its character sheets and location plates before generating scene visuals. Then generate Scene Images first in Visual — when you later generate Scene Videos, Flow automatically uses each scene's image as the starting frame.
Reference images not applied: Check the note under the model selector in Visual or Thumbnail. Models that do not support image references will display a notice; switch to Gemini, OpenAI (GPT Image 2.5) or Together AI (all three of its image models take references) when reference consistency is required.
Single bad image in a completed batch: You do not need to re-run the entire batch. Open the batch with View in Visual and click Regenerate on just the card you want to replace.

#Style Library and Import from Gemini issues

Gemini JSON fails validation on import: Make sure you copied the prompt from Import Style from Gemini so Gemini returns all 4 required pillars (aiStyle, sceneStyle, visualStyle, flowStyle). Do not paste a single-category skill file into the 4-pillar Style Family importer — use Import Skill (.md / .json) for single-pillar skills.
Gemini output was cut off mid-JSON: For long videos, Gemini may stop partway through the JSON. Click + Add next chunk on the Import page, ask Gemini to "Continue from the exact line where you stopped", paste the continuation into Part 2, and click Merge chunks & Import.
YouTube video style deconstruction does not start: Confirm the YouTube URL is a public video. If you already analyzed the exact same URL recently, Flow reuses the existing style analysis job instead of charging and queueing a duplicate.

#Narration failed

Open Audio history to see the provider's reason. Unauthorized or not enough credits means the voice API key is wrong or the account has no credits. A voice error means the chosen voice is no longer available; pick another voice.

#"Scene cuts are estimated from word counts"

The narration has no transcript (it was made before transcripts were saved). Regenerate the narration once in Audio; the editor timeline then cuts to the real speech.

#Final Review 5-point check is incomplete

If Final Review shows one or more incomplete checks, resolve the specific item and click Check again:

Script Approved failing: Open Script Viewer and approve the active script.
Scenes Complete failing: Open Scenes and make sure every scene has non-empty prompts.
Narration Complete failing: Open Audio and generate full-script narration for the approved script.
Visual Assets Ready failing: Open Visual or Assets and ensure every scene has at least one completed image or video.
Thumbnail Selected failing: Open Thumbnail and click Select on your chosen thumbnail version.

#DaVinci Resolve: empty timeline or clips not found

Use File > Import > Timeline… (not Import Media).
First verify that the Folder you'll unzip into path was filled in before download. If Resolve still asks to locate clips, click Yes and choose the media folder beside the XML.
Still empty? Drag the media folder into the Media Pool first, then import the timeline with Automatically import source clips unticked.

#Windows: "Path too long" when extracting

Extract to a short location, such as your Downloads folder or D:\Videos, with Extract all. Current downloads use short names, so this only affects very deep folders.

#CapCut: can't find where to paste the project

The folder is hidden. Press Windows key + R, paste %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft and press Enter. See CapCut.

#Editor shows offline or missing media

The files were extracted to a different folder than the one set in Final Review. Point the editor at the media folder once (DaVinci: Yes + choose folder; Premiere: Link Media; CapCut: relink), or download again with the right folder.