Troubleshooting video and audio

A media workflow goes wrong in one of two ways. Either it stops with a code: when the workflow is saved, when a run is submitted, or at a step. Or it completes, and the result is not right: the music is too loud, a voice arrives late, the captions drift, a generated clip does something it was asked not to do. The first kind always names its reason, and this page tells you which page explains it. The second kind has no code, so it is the kind to learn to recognise. Its causes are few and recurring, and they are listed below by symptom.

Media adds two things that data workflows do not have. Steps that call a provider can fail for reasons outside the workflow: a limit, a quota, a busy service. And media steps work on files, which can be too large, unreadable, or slower to process than you expect. Both are covered here.

Where to read the reason

• The run. GET /api/v1/executions/{id} (get_execution over MCP). A run that does not complete says why. error_message names up to three causes, each with the step’s label, its code and the underlying message. error_code is the first cause’s own code. A cause can be:

  • a step that failed;
  • some iterations of a step that failed (“2 of 4 iterations of step “Hear Each Speaker’s Voice” failed”);
  • a sub-workflow that completed partially, carrying its own reason.

  A quota exceeded deep inside a dubbing engine therefore reaches you as RATE_LIMIT, not as a generic failure.

• The app. The execution’s page shows the same reason in an amber box for a partial success, or a red one for a failure. Open the run on the canvas and select a step to see its error code, its message and, for an iterative step, the iterations that failed.

• The result. GET /api/v1/executions/{id}/result (get_execution_result) gives every output with its state:

  • present: it was produced;
  • absent: a decision held it back — a quality gate in route, a branch not taken — and it comes with a reason;
  • missing: the step that produces it failed.

• The trace. GET /api/v1/executions/{id}/trace gives, for every step, its status, duration, attempts, credits, and the models actually used. For an iterative step it also gives each iteration’s outcome.

• The measurements. Media Technical Info, the loudness report, the quality report and the dubbing manifest are outputs of the run itself. When a result looks wrong, they usually say where it went wrong.

Refused when the workflow is saved

Validation (validate_workflow, and every save and publish) catches what can be known before running. Each issue comes with the path of the wrong connection or parameter and a suggestion.

Code	Cause	Fix
CONNECTION_TYPE_MISMATCH	a video wired into an audio port, a caption file into a caption-track port	connect a port of the right type: Extract Audio turns a video into its sound
NATURAL_SPEECH_WIRING	a dubbing build is wired wrongly; the message names the node and the port	the wiring rules
RUNTIME_PRICING_ITERATION_UNSUPPORTED	a step priced on the length of its input (video transform, upscale) sits inside segments or a list	move it out of the iteration — Long media
model_not_allowed_for_capability	the model named cannot do what the node does	choose one the node lists — Generative
unknown_model_parameter, model_params_schema_unavailable (warnings)	a model setting was dropped: unknown to the model, or given without naming a model	check the model’s schema; name the model

Refused when the run is submitted

• 402 insufficient_credits. The organization does not have the credits the run needs to start. The estimate (estimate_execution) says how many it needs. Top up, then submit again with a new idempotency key.
• 402 credit_cap_reached. A daily or monthly usage limit of the organization or of the workspace is reached. Topping up does not help: work starts again at resets_at_utc, or when an owner or admin raises the limit.
• 400 validation_error. A required input is empty, or a value has the wrong shape; the message names the input. Give a media input as {"asset_path": "…"} with the path the upload returned, or as a public HTTPS URL — see Media files and preflight.

A step failed

A failed step stops its branch. The outputs that depend on it come back missing, and the run ends as partial_success or failed. The code tells you which page to open:

Codes	Page
INSUFFICIENT_CLIPS, EMPTY_CLIP, NOT_A_VIDEO, NOT_AN_AUDIO, ADD_AUDIO_ERROR	Editing video
AUDIO_TARGET_NOT_REACHED, AUDIO_QUALITY_FAILED, AUDIO_DURATION_RATE_OUT_OF_RANGE, AUDIO_SPEECH_OVERFLOW, INVALID_AUDIO_POLICY	Audio finishing — see below
MEDIA_POLICY_FAILED, QUALITY_GATE_FAILED, INVALID_MEDIA_POLICY, DUPLICATE_CHECK_ID	Media files and preflight and Quality checks
UNSUPPORTED_MODEL_CAPABILITY, TIMING_REQUIRED, PROVIDER_TIMING_MISSING, PROVIDER_SPEAKERS_MISSING, INVALID_SRT, OVERLAPPING_CAPTIONS, TEXT_OVERFLOW	Transcription and captions
EMPTY_TEXT, FONT_NOT_FOUND, FONT_MAPPING_REQUIRED, FONT_GLYPH_COVERAGE_INSUFFICIENT, TYPOGRAPHY_INVALID	Typography on video
SEGMENT_LIMIT_EXCEEDED, SILENCE_BOUNDARY_UNAVAILABLE, INPUT_MEDIA_TOO_LONG	Long media
HIGHLIGHT_NO_VALID_CANDIDATES, HIGHLIGHT_BUDGET_UNSATISFIABLE, HIGHLIGHT_CAPTIONS_EMPTY	Highlights
CAPTION_TRACK_INVALID, TRANSLATION_COVERAGE_INVALID, TRANSLATION_LANGUAGE_MISSING, GLOSSARY_INVALID	Translating captions
TRANSCRIPT_SPEECH_EMPTY, SPEECH_TIMING_PROVENANCE_MISMATCH, SPEAKER_VOICES_INVALID, CHILD_PARTIAL_SUCCESS	Dubbing: quality, costs and limits
PAYLOAD_VALIDATION, NO_OUTPUT, PROVIDER_AUDIO_TRACK_UNAVAILABLE, TARGET_TOO_CLOSE, TARGET_TOO_FAR	Generative video and sound

Some audio finishing steps fail on purpose when their result misses its target, so their codes deserve a word:

• AUDIO_TARGET_NOT_REACHED. Normalize Loudness could not reach its target within the tolerance, and Fail if Target Is Missed is on — it is by default. The usual cause is a very quiet or very short input.
• AUDIO_QUALITY_FAILED. The quality report found a violation, and Fail on Violation is on.
• AUDIO_DURATION_RATE_OUT_OF_RANGE. Fit Duration would have to speed up or slow down beyond the range you allowed, and Out-of-range Behavior is fail, its default. Widen the range, choose clamp, or give the audio a target closer to its length.

To keep delivering in these cases while still recording the problem, turn the fail option off and route the check through a Quality Gate.

A provider refused, or took too long

Steps that call a model — transcription, translation, voices, generation, video analysis — depend on a provider. A temporary refusal is retried automatically, up to three times: RATE_LIMIT (too many requests), SERVICE_UNAVAILABLE, OVERLOADED, TIMEOUT, SERVER_ERROR, and MEDIA_DOWNLOAD_FAILED (the provider could not download a picture or a document in time — Claude models fetch them from their address, and many steps asking at once for a file made seconds before can find it not yet reachable). A step that still fails after the retries ends with that code. In a list of iterations, only the iterations that ran out of retries fail. Run it again later, or at a quieter time; if it happens every time on large lists, split the work into smaller runs.

Some refusals are not retried, because another attempt would give the same answer:

Code	Meaning	Fix
QUOTA_EXCEEDED	the provider account behind the model has no quota or credit left	nothing to change in the workflow; the account must be topped up — on Madoo’s own keys, contact support
AUTH_ERROR, FORBIDDEN	the provider key was refused	on your own provider key, check it in the workspace settings
BAD_REQUEST, VALIDATION_ERROR, PAYLOAD_VALIDATION	the provider rejected a setting or an input	read the message; check the model’s settings
PROVIDER_QUEUE_TIMEOUT	the job waited in the provider’s queue far too long without moving, and was cancelled	run again
MEDIA_OUTPUT_TOO_LARGE	a video step (burnt-in subtitles, text, overlay, resize, speed, loop, merge…) made a file larger than the disk room it reserved — it re-encodes the whole video at near-lossless quality, so a strongly compressed source can grow several times	shorten the video, lower its resolution, or for subtitles use mode: sidecar (no re-encoding); if it keeps happening on an ordinary video, contact support

A generation that stays on waiting for provider is not stuck: the provider is still working, or the job is in its queue. Video generation takes minutes. Madoo checks the job every few seconds and does not give up while the provider reports it as queued or in progress.

Credits ran out during the run

A run that lists its work only at run time — segments, speakers, caption blocks — reserves the credits for each list when the list is known. If the balance is not enough at that moment, the step fails with INSUFFICIENT_CREDITS and the number of credits it needed. The run ends as a partial success and keeps what it has produced. If you set an admission_limits bound when you submitted, a list larger than the bound stops with ITERATION_LIMIT_EXCEEDED instead. If a usage limit is reached at that moment, the whole run stops with CREDIT_CAP_REACHED, keeping what it has produced.

The file is too large, unreadable or busy

Code	Meaning	Fix
MEDIA_TOO_LARGE, VIDEO_TOO_LARGE, AUDIO_TOO_LARGE	the file is over what the step accepts — 2 GiB for most	compress it, or cut it into segments
CORRUPT_OR_UNSUPPORTED_MEDIA, CORRUPT_OR_UNSUPPORTED_AUDIO	the bytes are not a readable video or audio file, whatever the extension says	open it with Media Technical Info; export it again as MP4 (H.264) or WAV/MP3
MEDIA_WORK_CAPACITY	the worker’s local space is busy with other media	nothing: it is retried automatically
MEDIA_PROBE_TIMEOUT, AUDIO_PROCESSING_TIMEOUT	reading or processing the file took too long	retried automatically; if it persists, cut the file
AUDIO_SOURCE_CHANGED	the file changed in storage while the step was reading it	retried automatically

The run is slow

• Generation takes minutes. A 5-second clip takes a model one to several minutes, plus the time in its queue.
• Iterations run four at a time per worker. Forty caption blocks voiced one by one take ten rounds of four; a dub runs its fitting rounds one after the other.
• Heavy files take time to move. Every media step reads its input from storage and writes its output back. Cut long masters once and work on segments only where the work needs it — see Long media.

The trace gives each step’s duration, so it shows where the time went.

The run completed, but something is absent

An absent output is not an error: a decision held it back. The result gives the reason, and the trace gives each skipped step’s skip_reason — see Branches and absence:

• The delivery is absent, and a quality gate is in route. The clip did not pass the policy. The gate’s report lists each broken rule with what was expected and what was found (MINIMUM_HEIGHT: expected 1280, actual 720).
• An optional branch did not run. No background track because none was asked for; no subtitles because the option was off. Check the input that switches it on.

The run completed, but the result is wrong

Symptom	Likely cause	What to do
the finished clip is louder or quieter than the target	the audio was levelled and then cut or mixed again; loudness is a measure of the whole file	level last, on the audio that is delivered; cut music to the clip’s length before mixing — Generative, Audio finishing
the music covers the voice	the music is mixed at a fixed level	duck the music under the voice (audio/duck) — Audio finishing
the sound drifts out of sync after joining segments	the segments overlapped, and joining does not remove the overlap	cut with overlap 0 before a merge — Long media
captions are off after a cut	the captions were made for the master, not for the edit	move them onto the edit with Project Captions — Highlights
speaker numbers change halfway through	the recording was transcribed in segments, and speakers are numbered per segment (SPEAKER_LABELS_SEGMENT_SCOPED)	transcribe in one pass, up to an hour — Long media
a dubbed line plays fast, or the next lines start late	the translation was longer than the time available (SPEECH_TIMING_DEGRADED_RATE, SPEECH_TIMING_REFLOWED in the quality report)	listen at the time given; give the line more room, or accept it — Dubbing: quality
a speaker has the wrong voice	the voices are assigned by what the model heard in each speaker’s sample	read the speaker voices output; fix the voice lists — Dubbing
captions show empty boxes for some letters	the font has no glyph for them	choose a font that covers the language — Typography
a highlight cuts mid-sentence or misses the best moment	the AI’s answer was cut short, or the clip limits leave no room	keep Max Tokens at 8192; loosen the minimum and maximum clip length — Highlights
a generated clip does something the prompt forbade	a model treats a prompt as a guide, not a rule	review, rephrase, or try another model — Generative
a video-to-audio or music step’s output sounds wrong for the scene	the prompt did not say what to leave out	say “no voices, no music” for a scene’s sound, “instrumental” for a music bed

A method that always works

1. Estimate first. The estimate uses the same models and settings as the run. A deferred price says which steps are measured at run time.
2. Measure at every hand-over. A free Media Technical Info after each step that matters — the generation, the mix, the final file — turns “it sounds wrong” into a number.
3. Try one short item before the whole list. One segment, one caption block, one five-second clip: the same workflow, a fraction of the credits and the time.
4. Read the reason, then the step. The run’s reason names the step; the step’s panel or the trace gives its code and message; this page and the linked pages give the fix.