Livepeer
Livepeer transcoding diagnostics distinguish stalled uploads, processing failures, and playback errors
Livepeer transcoding can look stalled when an upload hasn't finished, a job remains waiting, processing stops updating, or the asset has failed. Start with the asset identifier, then compare status.phase, status.progress, status.updatedAt, and status.errorMessage. Those fields separate transfer trouble from media processing and from a playback problem after the asset becomes ready.
Last updated:One status label rarely explains the cause by itself. Keep the same asset ID while checking input reachability, requested profiles, and returned media fields. Retry only after the request outcome or asset record identifies a failed or incomplete stage.
Check phase, update time, input readiness, requested profiles, and playback evidence separately to isolate a stalled job.
When progress and state disagree
The mismatch between the interface and the asset record is the first diagnostic clue. A screen may retain an old processing message after the asset has moved to ready or failed. Fetch the same asset ID again and compare its phase and update time with the application's stored response. A fresh terminal phase outweighs a stale spinner or cached percentage.
Transcoding time varies, so one unchanged progress value doesn't establish failure. Repeatedly unchanged updatedAt, progress, and phase over the application's observation window provide stronger evidence, especially when an error message appears. Preserve those values before changing the request.
The evidence carried by an asset record
The asset record connects the source, requested outputs, processing state, and playback identity. Reading those parts together prevents an upload problem from being mislabeled as a transcoder fault.
Phase and update time
The phase names the current boundary, while updatedAt shows when the record last changed. uploading belongs to transfer, waiting precedes active processing, processing represents media work, and ready or failed are terminal phases. Progress adds context, but it shouldn't replace the phase or timestamp.
Profile and media fields
The profiles array describes the renditions requested for the asset. Its entries can include dimensions, bitrate, frame rate, encoder, and codec profile. By contrast, videoSpec describes parsed source media when that information is present. Compare those fields to determine whether the requested conversion is compatible with the parsed source; a difference alone doesn't imply a network-wide outage.
Storage and playback records
The storage.status object tracks persistence separately from the main asset status and may carry its own task identifiers or error message. A playbackId identifies the asset for playback lookup, but it doesn't replace the processing phase. Use playback information after readiness to test delivery, not to infer an unfinished upload.
Which part of the job has actually stopped?
The job stopped at the first stage without completion evidence. Separate transfer, processing, and delivery before choosing a recovery action.
Transfer boundary
The transfer boundary remains open while the asset reports uploading and the client hasn't confirmed the upload completed. Check whether the local file stayed readable and whether the upload request finished. A partial transfer can't become a valid transcode merely because an asset record already exists.
Processing boundary
The processing boundary begins after the complete input is available. A waiting phase doesn't show active transcoding has started, and processing alone doesn't prove forward movement. Compare successive records for phase, progress, update time, and an error message. Continue following the existing ID while those fields still change.
Delivery boundary
The delivery boundary starts after the asset becomes ready. Playback can still fail if the application uses a direct URL instead of a source returned by Playback Info, doesn't satisfy the asset's access policy, or expects a rendition it never requested. Retrieve playback information using the playback ID, then test a returned source under the intended policy.
Input compatibility before another attempt
Input compatibility determines whether the service can obtain and parse the complete source. A URL-based source must remain reachable without a browser session, local network path, or expired authorization. For a local file, confirm the selected upload method completed before investigating rendition settings.
TUS supports resumable asset uploads after an interrupted transfer. A simple PUT upload needs a successful request completion. If transfer evidence is incomplete, repair that boundary before resubmitting the same media through a different profile.
The service must also be able to parse the source. A file opening in one desktop player doesn't establish compatibility with every remote pipeline. Inspect the returned videoSpec and errorMessage instead of guessing from the filename extension. Change one dependency at a time so you can tell which change affected the outcome.
Requested renditions and actual output
Requested renditions define the outputs the transcoder should produce. When profiles are supplied, compare their names, dimensions, frame rates, encoders, and codec profiles with the asset record. If profiles are omitted, the service can derive default profiles from the source input. An assumed resolution missing from that derived set isn't evidence of a stalled job.
Source metadata and output profiles answer different questions. videoSpec shows what the service read, while profiles shows what it was asked to create. A failed job calls for the recorded error and a corrected input or profile. A ready job with an unexpected rendition calls for an expectation check before any new submission.
Seven diagnostic states and recovery boundaries
The evidence below distinguishes a recoverable live condition from a terminal state or a delivery problem.
| Observed evidence | What it establishes | Recovery boundary |
|---|---|---|
| No asset ID returned | No durable job record was confirmed | Inspect the request outcome and correct any confirmed error before creating the asset again |
uploading remains current
|
The transfer boundary is still open | Resume TUS or confirm the PUT result |
waiting remains current
|
The asset hasn't entered active processing | Keep the ID; if the status stays unchanged through the application's observation window, escalate |
processing with a newer update time
|
The status record has changed | Continue observing instead of duplicating the job |
processing with no fresh evidence
|
A stall is possible but not yet a terminal fact | Record the unchanged fields and use a bounded escalation |
failed with an error message
|
The attempt reached a terminal failure | Correct the named cause before a new submission |
ready with unusable output
|
Processing ended; delivery or expectations differ | Inspect profiles, playback information, and access policy |
| Keep the same asset identifier until a terminal failure appears or the evidence shows the original submission never completed. | ||
A local timeout should trigger inspection, not silently redefine one of these states. Use the live record to decide whether to wait, repair an input, adjust a profile, or investigate playback.
Bounded recovery after a terminal failure
Recovery should preserve the failed record, isolate one dependency, and stop before an unchanged retry creates duplicate work.
Reversible checks
Reversible checks start by fetching the same asset again, confirming the source remains obtainable, and comparing requested profiles with parsed media details. Recheck the stored response before altering anything. These actions preserve the original evidence and can expose a stale interface without creating another asset.
New submission boundary
A new submission makes sense when the original record is failed, or when no asset was created, and the suspected cause has been corrected. Changing both the media and every profile at once may produce a working job without revealing which incompatibility mattered. Retain the old asset ID beside the replacement ID.
Escalation evidence
Escalation evidence should include the asset ID, source type, requested profiles, phase, progress, update time, and sanitized error message. Remove bearer tokens, signed source addresses, and webhook secrets from logs or support material. Those credentials don't help explain transcoding state and can grant access beyond the affected job.
Verification before closing the incident
Final verification requires a terminal asset state and usable output, not merely a completed retry request.
-
Confirm
readybelongs to the intended asset ID. - Match returned profiles with the renditions the application expects.
- Resolve playback sources through the playback ID.
- Test playback under the intended public or signed policy.
- Store the terminal phase and update time in the application record.
A failed phase confirms the attempt ended in failure, but it doesn't validate output. If any readiness check remains unresolved, keep the incident attached to that boundary rather than sending the identical job again.
Key questions about Livepeer transcoding
How long should a Livepeer transcode remain in processing?
No single duration applies to every transcode. Source duration, media characteristics, requested renditions, upload completion, and available processing capacity can all affect elapsed time. Treat an application timeout as an alert threshold, not proof the job failed. Compare the same asset's phase, progress, and update time across polls. A returned failed phase is terminal evidence; an unchanged processing phase needs further inspection or escalation.
What happens if a source URL expires while Livepeer is fetching it?
The job can fail if the service can't obtain the complete source before the URL becomes inaccessible. Browser cookies, local addresses, and short-lived page state don't make a remote source reachable by the processing service. Keep the source available for the required fetch, inspect the asset's error message, and replace the URL only after confirming access caused the failure. Don't expose a long-lived unrestricted address merely to avoid expiry.
Is a playback ID proof the transcoding job finished?
No. A playback ID identifies the asset for playback lookup, but the asset can have that identity before processing reaches ready. Use status.phase to determine whether transcoding finished. After readiness, retrieve playback information and test one of the returned sources. A playback ID without a ready phase or usable playback source doesn't establish successful output.
Can a signed playback policy cause an error after transcoding succeeds?
Yes. A ready asset can still reject a playback request when the application doesn't satisfy its signed access policy. That failure belongs to delivery or authorization, not transcoding. Confirm the asset is ready, retrieve playback information with its playback ID, and test the request using the intended policy. Repeating the transcode with identical media won't repair missing playback authorization.
Why can an asset be ready without a manually listed set of profiles?
Livepeer can derive default profiles from the source when the upload request doesn't specify profiles. A ready asset may therefore have valid renditions even though the application didn't submit a custom list. Read the profiles returned on the asset and compare them with the renditions the player expects. If a specific output is required, define and validate that request rather than treating a different default set as a stall.