# Error and warning reference

> A searchable catalogue of the messages RoughCut shows, what each one means, and the corrective action.
>
> Verified against the current RoughCut app on 28 August 2026
> https://www.roughcuteditor.com/docs/error-reference

This is a searchable list of the messages RoughCut shows you, grouped by area: setup, files, transcription, AI provider, cutting and export, purchases, evaluation, and permissions. Each entry gives the message as it appears, what it means, the first action to take, and where the full explanation lives. Warnings are included alongside failures, because several of RoughCut's most important messages are cautions rather than errors — variable frame rate, unclear transcription, degraded transcription, and an isolated Second Look failure all leave you with a usable result. If you are working from a symptom rather than a message, start from the troubleshooting page instead.

## How to use this page

Search the page for a distinctive phrase from your message. Messages with `%@` or a number in them show a value in the app — match on the surrounding words.

If you have a symptom rather than a message, [Troubleshooting by symptom](/docs/troubleshooting) is the better starting point.

## Setup

| Message | Meaning | First action |
|---|---|---|
| `Download the Whisper model in Settings first.` | On-device transcription needs the speech model | `Settings → Models & Data → Download from Hugging Face` |
| `The speech model (~1.6 GB) is required for transcription.` | Same, shown in Settings | Download or import the model |
| `Whisper model missing at <path>. Download or import it in Settings.` | The file is not where RoughCut expects | Clear `Whisper model path`, then download or import again |
| `Model download failed: <reason>` | The download did not complete | Retry, or use `Copy download link` and `Import model file…` |
| `Model import failed: <reason>` | The chosen file could not be copied in | Confirm it is the `.bin` file and try again |
| `Could not save configuration: <reason>` | Settings could not be written to disk | Check free disk space, then `Save Configuration` again |

Full detail: [Install the local speech model](/docs/speech-model).

## Files

| Message | Meaning | First action |
|---|---|---|
| `Unsupported file type .<ext>. Video: mp4, mov, mkv, avi, m4v. Audio: wav, mp3, m4a.` | The extension is not accepted | Convert to a supported format |
| `RoughCut can't open "<name>". Video: … Audio: …` | A file handed to RoughCut from elsewhere is unsupported | Same as above |
| `source media not found: <path>` | The source file moved or was deleted | Restore it, or re-add the file and process again |
| `Lost access to the source video. Re-add the file and process again.` | The stored file permission is no longer valid | Re-add the file in a new job |
| `<name> is not ready yet.` | You tried to export an artifact the job has not produced | Wait for the job to finish |
| `SRT file is missing from the job folder.` | The transcript artifact is absent | Run the transcription again |
| `Could not load the transcript: <reason>` | The transcript file could not be read | Run the transcription again |

Full detail: [Choose video and audio inputs](/docs/file-inputs).

## Transcription

| Message | Meaning | First action |
|---|---|---|
| `Cloud transcription needs your OpenAI API key.` | Cloud selected with no key saved | Add the key, or switch the job to `On-device` |
| `Cloud transcription needs your OpenAI API key. Add it in Settings → LLM, or switch this job to on-device transcription.` | Same, at job preflight | As above |
| `transcription produced no words — cannot build a cut` | No speech was recognised | Confirm the file has audible speech; try a separate mic track |
| `OpenAI model '<model>' returned a transcript without word timestamps…` | The chosen cloud model does not return word times | Set `OpenAI transcription model` back to `whisper-1` |
| `OpenAI cloud transcription failed (<model>): <reason>` | The cloud request failed after a retry | Check key and network, or switch to on-device |

### Transcription warnings — not failures

| Message | Meaning | What to do |
|---|---|---|
| `<n> sections couldn't be transcribed cleanly. They are kept in your cut — use ⏵ to listen and decide.` | Regions were kept rather than silently dropped | Listen to each flagged range before relying on it |
| `<n> sections flagged — listen before trusting` | Same, on a transcript result | Listen and correct outside RoughCut if needed |
| `Unclear transcription — listen before trusting` | Row-level tag on a kept segment | Audition that row |
| `Transcription may have degraded here — listen` | A weaker signal than the above | Audition that row |
| `Transcription noise over quiet section` | Recognised words over near-silence | Usually safe to remove |

Full detail: [Read and verify a transcript result](/docs/transcript-results).

## AI provider

| Message | Meaning | First action |
|---|---|---|
| `No API key for provider '<provider>'. Add it in Settings, or disable bad-take removal for a silence-only cut.` | The editing pass needs a key | Add a key, or turn `Bad-take removal` off |
| `Summarizing needs your Gemini or OpenAI API key.` | Goal summarising needs a usable key | Add a key in Settings |
| `Over the 500-character limit (<n>).` | The video goal is too long | Shorten it, or use `Summarize with AI` if you have Pro |
| `The model could not fit the goal into 500 characters (got <n>). Try again, or trim it by hand.` | Summarising failed twice rather than truncating silently | Retry, or shorten the goal yourself |
| `llm_editor_exemplars=<n> but the exemplar bank at <path> is unusable: <reason>` | A bank exists but cannot be parsed | Re-import a valid bank, or set `LLM editor exemplars` to 0 |
| `Exemplar bank import failed: <reason>` | The chosen file could not be imported | Confirm it is a valid `exemplars_v2.json` |

### Editor notices — not failures

| Message | Meaning |
|---|---|
| `LLM editor: skipped — silence-only cut.` | `Bad-take removal` was off. This is the expected silence-only result |
| `Second Look could not run — this cut is the standard single-pass result. <reason>` | The refine pass failed and was isolated. Your standard cut is intact |

## Cutting and export

| Message | Meaning | First action |
|---|---|---|
| `cut plan kept nothing — refusing to export an empty timeline` | Everything would have been removed | Use a stricter recording environment or raise `Min silence (sec)` |
| `Export failed: <reason>` | The file could not be written | Check the destination and free space |
| `Could not create job: <reason>` | The job could not be set up | Check free disk space, then retry |
| `Job failed` | Heading on a failed job | Read the message beneath it |
| `media info missing for a cutting job` | Media could not be probed | Confirm the file plays, and try a constant-frame-rate version |

### Export and cut warnings

| Message | Meaning |
|---|---|
| `Variable frame rate detected. For best relinking results, transcode to constant frame rate before import.` | Your source is VFR. The cut still works, but relinking is more reliable with CFR |
| `Smart Silence picked <n> dB` | The measured threshold Smart Silence chose for this job. Informational |
| `Cut list recomputed — re-export the FCPXML.` | Your review changes are applied. **Export again** — a previously exported file does not update |

## Purchases

| Message | Meaning | First action |
|---|---|---|
| `The App Store returned no products for this app right now. Please retry in a moment.` | A temporary App Store issue, not a purchase failure | Retry |
| `The App Store did not return this product just now. Please retry.` | Same for a single product | Retry |
| `The App Store did not return the subscription plans just now. Please retry.` | Same for the Pro plans | Retry |
| `The App Store request failed: <reason>` | The store request errored | Check the network and retry |
| `The App Store could not verify this purchase: <reason>` | Verification failed | Retry, then `Restore Purchases` |
| `No previous purchases found for this Apple Account.` | Nothing to restore on this account | Confirm you are signed in with the purchasing Apple Account |
| `No active RoughCut Pro subscription found for this Apple Account.` | No live subscription found | Check App Store subscription settings |

Full detail: [Trial, core unlock, and RoughCut Pro](/docs/plans-purchases).

## Evaluation

| Message | Meaning | First action |
|---|---|---|
| `Golden-set folder not connected. Grant access in Settings → Models & Data first.` | No folder permission stored | Grant access once in `Models & Data` |
| `An evaluation is already running.` | Only one run at a time | Wait for the current run |
| `mode must be 'smoke', 'full', or a subset list defined in eval_manifest.json…` | An invalid run name | Fix the manifest key |
| `Cloud transcription needs your OpenAI API key — add it in Settings → Full → Transcription, or switch the eval back to on-device.` | A cloud evaluation with no key | Add the key or switch back |
| `Regression flagged: word-F1 mean dropped more than 3 points vs the previous run.` | A caution, not a failure — the run still wrote | Compare against the same mode and gold |

Skip reasons per clip — `clip_dir_missing`, `missing_media`, `missing_gold` — are recorded rather than hidden. See [Build a golden set](/docs/golden-set).

## Validation messages

These appear in red under the controls and block `Process` until fixed.

| Message | Valid range |
|---|---|
| `Silence threshold must be between -60 and -10 dB.` | −60 to −10 |
| `Min silence must be between 0.1 and 5 seconds.` | 0.1 to 5.0 |
| `Aggressiveness must be conservative, standard, or aggressive.` | Those three values |
| `Language must be auto, en, or ar.` | Those three values |
| `Video goal must be 500 characters or fewer.` | Up to 500 characters |

## A message that is not here

Send it to support exactly as written, with what you were doing when it appeared. See [Contact support](/docs/contact-support).