Troubleshooting

Most run problems fall into a handful of shapes. This page covers the common ones and what to do about each.

A step failed

The run view marks the failed step in red and shows its error next to it. The message is truncated to fit; hover it to read the whole thing, which is usually where the actionable part is.

Once you know why it failed:

Fix the cause, whether that is a parameter, an input, or a service key.
Use the ↩ control on the step that failed, not ▶ Run on the template. That restarts from that step inside the same run group and reuses everything before it. Running the template again starts from scratch and pays to regenerate the earlier steps. See Reusing work between runs.

A failed run that never completed a real step does not count against your run limit.

Common step failures

Error looks like	What it means	Fix
`secret "OPENAI_API_KEY" not configured`	The step needs a service key that is not set	Add it under Workspace Settings → Variables & Keys
An authentication or permission error naming a provider	The key is set but the provider rejected it	Check the key is correct and still active on the provider's own dashboard
A quota, credit, or billing error naming a provider	Your account with that provider is out of credit	Top up with the provider; nothing in Puffin Ship can work around it
`input "source" is required`	A step is missing an input	Open the step and wire its input to a file or an earlier step
A file cannot be found	The name in the step does not match a file in the workspace	Check the filename in the Files panel, including its extension

"API keys required" before the run starts

If your template uses a processor whose service key is not set, the run is refused before it does any work and a dialog lists exactly which keys are missing and where to get each one.

Paste the key and choose Whole workspace (available to every template there) or This template only. The run then continues.

This check confirms a key is present, not that it works. A wrong or expired key gets past it and fails at the step that uses it, with the provider's own error message.

The provider rejected my key

Third-party services are billed to you and authenticated with your key, so when one refuses, the fix is with that provider:

Check the key itself. Copy it fresh from the provider's dashboard. Trailing spaces and truncated pastes are the usual culprits.
Check it is still active. Keys get rotated and expire.
Check your balance. HeyGen, ElevenLabs, and Google all stop serving when credit runs out, and the error often says so.
Check the key has the right permissions, if the provider scopes keys.

Update the key under Workspace Settings → Variables & Keys, then re-run from the failed step. Never work around a rejected key by turning off quality settings on a step; fix the key.

A run seems stuck

Check the run's status before assuming it is stuck:

Awaiting review. The run is waiting for you. Scroll to the review gate in the run view and answer it. There is no deadline, and the run resumes exactly where it left off. See Review gates.
Awaiting recording. A step is waiting for you to record a take in the browser. See Recording in the browser.
Running. Some steps are genuinely slow. Generating video, synthesizing speech, and rendering an MP4 all take minutes, and a step that generates several clips takes longer still. The run view updates on its own; you do not need to reload.
Queued. The run is waiting its turn behind other work and will start on its own.

If a run really is wedged, the Kill button at the top of the run view stops it. Killing a run does not throw away the steps that already finished: open the run's group and start another run there, and their work is reused.

The export is not what I saw in the preview

Export happens from the finished run's timeline view. If you adjusted clip timing there, re-export so the change is included; a previously rendered MP4 reflects the state at the time it was rendered. See Editing and exporting a finished run for the full rundown of the timeline view.

If a clip is missing from the finished video entirely, check whether it is a disabled variant. Steps using content_variants place several options at the same position with only one enabled. See Run groups and variants.

I hit the run limit

Your plan gives you a set number of runs in a rolling time window (for example 50 runs per 5 hours), not a fixed daily total. Once you are at the limit, the oldest run in the window has to age out before you get a slot back. See Run limits for what counts and how to make it go further.

New runs are paused

Sometimes a banner appears saying new runs are paused, either because the platform is at capacity or because maintenance is under way. While it is up:

Runs already going keep running, and finish normally.
Everything else still works. You can edit templates, upload files, watch a run in progress, and export a finished one.
Starting a new run is refused with the same message the banner shows.

If a time is given, that is when we expect to be taking new runs again. There is nothing to do at your end except start the run once the banner clears.

Save and Run are greyed out in the editor

The template's YAML does not parse, so there is nothing valid to save or run. Open the YAML tab in the middle of the editor: the reason and the line number are shown above the document, and the offending text is underlined. Common causes are a stray colon in an unquoted value, a line indented with a tab instead of spaces, and an opening bracket or quote with no closing one.

Your text is not lost while this is true. It stays in the editor exactly as you typed it, and Cmd/Ctrl+Z will walk it back. As soon as the document parses, both buttons come back.

Still stuck

Send us a report with the run name, the step that failed, and the error message. That is usually enough for us to reproduce it.