Troubleshoot Media Services

Media Services logo v3

AMS website | Code Samples | Troubleshooting guide

Find the causes and solutions for issues with Media Services.


Many issues can be resolved by migrating to the Media Services v3 API or by reading the live streaming best practices guide.

Account issues

Cause Solution
You may be attempting to use the features of the v3 API with a v2 account or a v2 API implementation. Update your code to use the v3 API. For more detailed assistance, see the Migration guide.

Common video playback issues

  • Videos take a long time to start playing.
  • Videos are blurry when they start playing.
  • Video quality is low.
  • Video doesn't play at all or shows a black screen.
Cause Solution
You may be attempting to reach a large audience without using a CDN which is causing latency issues. Add a CDN to your streaming locator. For more information about using a CDN, see Stream content with CDN integration.
You may not have implemented dynamic packaging. For more information on implementing dynamic packaging, see Dynamic packaging in Media Services v3.
You may have what is known as "noisy neighbors", which means that you are sharing compute resources with other customers. To avoid "noisy neighbors" upgrade from a standard streaming endpoint to a premium streaming endpoint with dedicated streaming units.
You may be using an older browser to view videos. Upgrade your browser.
You may be using a 3rd party player and filters. Add audio-only=false to the streaming URL like so,audio-only=false)

You can't play an MP4 file from the asset

Cause Solution
Azure Media Services is designed to use a manifest file rather than playing full size MP4 streams directly. The manifest file tells the player which encoded media fragments to play and in what order. Use one of the provided media encoders to create media fragments and manifest file. For more information about encoding see Content-aware encoding and Encode with an auto-generated bitrate ladder encoding.
The file name contains reserved characters. Remove the reserved characters from the file name.

Reserved characters

  • Media Services uses the value of the asset file name when building URLs for streaming content. For this reason, percent-encoding is not allowed. The value of the name property cannot have any of the following percent-encoding-reserved characters: !*'();:@&=+$,/?%#[]". Also, there can only be one '.' for the file name extension.
  • The length of the name should not be greater than 260 characters.

Encrypted content won't play in offline mode.

Cause Solution
The player that you are using to play the downloaded AES encrypted videos in offline mode on iOS devices handles how those videos play. The cause isn't with Media Services. Review the documentation for your chosen offline video player.

The audio is out of sync.

Cause Solution
Video packets are being delivered late. Possible solutions:

1. You may have implemented a storage versioning policy that was turned on automatically which causes buffering and disconnects. Remove the policy and turn off automatic storage versioning.
2. Enable a CDN.
3. Use a Premium streaming endpoint with enough reserved units.

The player request for the VTT file caused CORS errors.

Cause Solution
CORS rules setup Set up CORS rules for your storage account or CDN.

Yuu can also get the download URL of the VTT file from the asset.

A streaming endpoint won't start.

Cause Solution
You may have created a custom policy that enables only HTTPS. This is not currently supported by Media Services. Possible workarounds:
1. In the Azure portal, disable your custom policy.
2. Create a streaming endpoint with a CDN enabled and disable HTTP for the CDN endpoint.
1. Don't enable the CDN for the streaming endpoint with the portal or the API.
2. Instead, go to the Azure CDN page in the Azure portal or use the Azure CDN API to create an endpoint that points to the Media Services endpoint, setting the origin for the CDN endpoint to the hostname for the streaming endpoint.
You may have stopped a streaming endpoint with a CDN. See Streaming endpoint won't stop

A streaming endpoint with a CDN won't stop.

Cause Solution
When you enable the CDN for any streaming endpoint, the CDN endpoint won't be created until you start the streaming endpoint. This reason is that during the start process, our platform will create the CDN endpoints and link them to the streaming endpoint (including configuring the custom hostname).

During the stop process for the streaming endpoint, our platform should delete the CDN endpoint. Therefore, if the streaming endpoint is in stop state, the CDN endpoint will not exist nor point to the streaming endpoint.

However, in some scenarios, when AMS calls the CDN to delete the CDN endpoints, it fails to delete endpoints due to caches on the CDN. This results in a hostname conflict problem if the CDN endpoint is still there and triggers the stop streaming endpoint issue.
Manually delete the CDN profile and then delete the streaming endpoint and setup a new one.

Streaming endpoints don't appear after moving account to a different subscription.

Cause Solution
It takes some time for streaming endpoints to be moved to the new subscription. Wait for 2 hours and check that your streaming endpoints are appearing in the new subscription.

On-premises encoder isn't sending data to the live event.

Cause Solution
You may be using an encoder that hasn't been tested with Media Services. Please see Verified on-premises live streaming encoders.
The on-premises encoder may not be configured correctly. Confirm that you have correctly configured the on-premises encoder.

Encoding seems to be taking a long time.

Most encoding duration issues can be resolved by configuring the encoder settings to control the balance between speed and quality. For faster encoding, set it to speed mode.

Cause Solution
The mezzanine file may be very large. File size is equal to the bitrate multiplied by duration. None
There are a high number of output layers. Reduce the number of output layers.
Output layers have high resolution. Reduce the resolution of the output layer to the bitrate you intend to stream media.
The mezzanine file may be complex, especially if you are encoding a 4k resolution file. None

Transform failures

Cause Solution
You may have gone over the quota for transforms per account which is 100. Delete unused transforms.

Unable to upload media

You are unable to upload media to a storage account.

Cause Solution
You are attempting to use HTTP. Use HTTPS. The HTTP protocol is no longer supported for uploading content.
You aren't waiting long enough for the storage account to be deployed. If you created the storage account programmatically, add code to test that the storage account is deployed before attempting to upload media.

CORS issues

Cause Solution
If you are attempting to use preflight requests containing traceparent headers, you will receive CORS errors. At this time, Media Services doesn't support preflight requests. We are aware that preflight requests are of value to our customers. Don't use preflight requests until the feature is available.

Storage account connection issues

Disconnected state

The "Disconnected" state for a Media Services account indicates that the account no longer has access to one or more of the attached storage accounts due to a change in storage access keys. Up-to-date storage access keys are required by Media Services to perform many tasks in the account.

The following are the primary scenarios that would result in a Media Services account not having access to attached storage accounts.

Cause Solution
The Media Services account or attached storage account(s) were migrated to separate subscriptions. Migrate the storage account(s) or Media Services account so that they're all in the same subscription or use managed identity for storage account authentication if your storage account is in the same tenant.
The Media Services account is using an attached storage account in a different subscription as it was an early Media Services account where this was supported. All early Media Services accounts were converted to modern Azure Resources Manager based accounts and will have a Disconnected state. Migrate the storage account or Media Services account so that they're all in the same subscription or use managed identity for storage account authentication if your storage account is in the same tenant.

Media Services account cannot access storage account

Cause Solution
The Media Services managed identity doesn't hasn't been given the Storage Blob Data Contributor role. To check this in the Azure Portal, first find out which identity is set for the storage account by selecting "Storage accounts" from the menu of the Media Services account, this should be either "System-assigned" or the name of a user-assigned Managed Identity. Next, go to the storage account in the portal, select "Access Control (IAM)" from the menu, select "Role assignments" from the toolbar, then add the role assignment. When adding the role assignment, the Role should be set to "Storage Blob Data Contributor" and the members should be set to the Managed Identity used by the Media Services account to access the storage account. After adding the role assignment, it may take a few minutes for the change to take effect.

Azure Media Indexer 2 isn't being returned in list of media processors.

Cause Solution
Azure Media Indexer 2 was deprecated on January 1st, 2020. Migrate to the Media Services v3 API.

A network error caused the video download to fail part-way.

Cause Solution
This error is usually the result of network connection issues on the client side and not with Media Services. Contact your network administrator or use Fiddler or F12 browser debugging to see the underlying error.

Downloading issues

You may have received the following error:

"While trying to download the input files, the files were not accessible, please check the availability of the source"

Cause Solution
If you are using a SAS token to access the file, it may have expired. Adjust your code to check that the token hasn't expired before using it to authenticate.

Excessive and intermittent 5xx errors

Cause Solution
On-premises encoding may have been implemented improperly. Check that your encoder is configured properly.
You may be using a non-tested on-premises encoder Use a tested on-premises encoder and check that it is configured properly.
The caching ratio between streaming endpoint and CDN may be insufficient. 1. Adjust the caching ratio so that the CDN is handling more traffic.
2. Adjust the streaming optimization rule for the CDN.
Filter configuration may be incorrect. Check that your filters configured properly.

See the Live streaming best practices guide.

General code errors

You may be experiencing errors in your code that are not covered by streaming endpoint error codes, live event error codes, or job error codes references.

Cause Solution
You may be attempting to use an object, property or method that is not included in an older version of the API. Upgrade your API library in your development environment.

If you haven't found the solution to your problem, contact Media Services Support.

Get help and support

You can contact Media Services with questions or follow our updates by one of the following methods: