Fast is fine, but accuracy is everything.
—Wyatt Earp

Issues pop up outta nowhere.

They try to corner you. They try to kill your streaming workflow.

Never fear, streaming engineer. We’ll help you stay vigilant in your video coding O.K. Corral. We got your back. We’re your Doc Holliday. By the end you’ll troubleshoot your way out.

And that pesky problem will be run outta town on a rail.

Below lies a guide to Unified Streaming problem-solving steps we hope you’ll find handy. It’s for you DIY outlaws, you lone wolves who want to fight back first as best you can, before raising a ticket.

For everyone else, we’ll round up our trusted posse to solve your issue. So beneath the troubleshooting manifesto, we’ve listed some suggestions to consider when you raise a ticket. Think of it as a wanted” poster, describing how we want you to help us help you.

The reward? To be back up and running as quickly as possible, instead of ducking for cover down a blind alley.


  1. Start with our documentation. Is your workflow correct? Are you using the right options for what you’re trying to achieve? Have you followed our best practices? Is what you’re trying to do actually even possible?

  2. Try the same steps in our latest beta. Often you’ll encounter problems we’ve fixed in a later version of our software. We don’t backport fixes. If the problem’s fixed in a later version, you’ll need to update your software to fix the issue. if updating your software isn’t possible, you can ask us if we know of a workaround, of course.

  3. Check out our multi-tool Unified Validator. It can provide quick advice on content issues. Fix any must-fixes or should-fixes and retest. Did this solve your issue?

  4. If you’re using DRM, verify that the problem is still present in the clear (without DRM).

  5. Cross-check to see that the problem is consistent across different OS/​browsers/​players. Your issue may be a third-party issue, rather than a Unified Streaming one. Does the behavior change over different versions of the above? A bug may have been recently introduced.

  6. Try to detect what has changed if you’ve changed your workflow recently. When something that *was* working, suddenly *isn’t* working, then the change could very well be the culprit.

  7. See if you can replicate this behavior with different material or our test content. Visit https://​docs​.uni​fied​-stream​ing​.com/​i​n​s​t​a​l​l​a​t​i​o​n​/​v​e​r​i​f​y​.​h​t​m​l​#​t​e​a​r​s​-​o​f​-​steel

  8. Check your logs and see what they say. Between readouts from your terminal (use v ‑4 for a more verbose output), Access, and Error logs from Origin and/​or logs from players etc., is it possible to see the issue?

  9. Try to simplify your workflow as much as possible. In cases where you use a CDN or caching layers, what happens when you hit the Origin directly? The problem could lie in another layer of your workflow, so workflow simplification could untangle the problem.

  10. Simplify your command lines/​number of tracks, etc, and try to replicate the error. This may help you pinpoint where issues are being introduced.

  11. Make use of Apple’s mediastreamvalidator tool and give a listen — that is, if your problem is with HLS.

Raising a ticket

Any and all the information above is useful to us when you’re raising a ticket. When you give us all the pertinent details, then you’re happifying us, cause then we don’t have to hold our horses and re-investigate.

Try to include the following in any tickets you raise:

  • A detailed explanation of what you’re trying to do and how you’re trying to do it, including example command lines, etc. If you’re experiencing an issue, please try to explain what you did, what happened, and what you expected to see. Try to explain not only what the problem is, but what further issues the problem is causing you, too. If this problem’s linked to other tickets you have open with us, please include the ticket number(s).

  • A detailed explanation of your setup and workflow including OS/​browser/​players and versions used for each of these, and of course which version of our software you are running.

  • A detailed explanation of how we can easily replicate the problem you are seeing. For example, a request we can make against the material, or a command line we can run against your material.

  • A detailed explanation of what steps you have taken so far, as per above, and what results you got.

  • We’ll provide FTP details for you to upload material where necessary.

    a. Please try to provide, at minimum, all information necessary for us to replicate the issue.

    b. Please try to name content so it’s easy for us to see what you are doing, or provide easy-to-read scripts that can be run to replicate the issue.

    c. Please try to include only the time range required for live material and/​or logs.

    d. If you feel it’s necessary, include config files from your setup.

That’s it. Whether you ride alone, or you ride with us and raise a ticket so we can ambush the issue together, we hope your video workflow varmint dies a quick — and entirely expected — death.

Happy trails, partner.