# MediaTailor ad skipping troubleshooting guide
Ad skipping is one of the most common issues that MediaTailor customers report. This guide helps you identify ad skipping issues and provides step-by-step troubleshooting procedures.
## Symptoms and impact
When ad skipping occurs, you might observe the following symptoms:
+ Ads don't appear during expected ad breaks
+ Ad breaks show content instead of advertisements
+ Inconsistent ad playback across different viewing sessions
+ CloudWatch logs showing `AdSkipped` events with various skip reasons
Ad skipping directly impacts revenue and can create poor viewer experiences. Address these issues promptly to maintain optimal performance.
## Identifying skip reasons
Use CloudWatch Logs Insights to query the `MediaTailor/AdDecisionServerInteractions` log group for skipped ads:
```
fields @timestamp, avail.availId, skippedAds.0.skippedReason, skippedAds.0.creativeUniqueId
| filter eventType = "FILLED_AVAIL" and ispresent(skippedAds.0.skippedReason)
| sort @timestamp desc
```
This query returns the most recent ad skip events with their specific reasons to help you identify patterns.
**Topics**
+ [Symptoms](#ad-skipping-symptoms)
+ [Skip reasons](#identifying-skip-reasons)
+ [NEW\$1CREATIVE skipping](troubleshooting-new-creative-skipping.md)
+ [ADS timeout skipping](troubleshooting-ads-timeout-skipping.md)
+ [VAST parsing skipping](troubleshooting-vast-parsing-skipping.md)
+ [Duration mismatch skipping](troubleshooting-duration-mismatch-skipping.md)
+ [Session variable skipping](troubleshooting-session-variables-skipping.md)
+ [Monitoring ad skipping](monitoring-ad-skipping-issues.md)
+ [Prevention best practices](preventing-ad-skipping-best-practices.md)
+ [Reference materials](ad-skipping-reference-materials.md)
# MediaTailor NEW\$1CREATIVE ad skipping troubleshooting
When ads are skipped with the `NEW_CREATIVE` reason, AWS Elemental MediaTailor encountered an ad that requires transcoding before insertion. This troubleshooting guide explains the causes and provides step-by-step resolution procedures.
## What causes NEW\$1CREATIVE skipping
MediaTailor transcodes ads based on three key factors: creative ID, AWS Account ID, and transcode variant set (the playback renditions for the underlying content stream). When any part of the creative ID or transcode variant set differs, MediaTailor recognizes the ad as a new variant that requires transcoding.
### Bitrate changes
Bitrate changes can cause NEW\$1CREATIVE skipping when the bitrate doesn't match after rounding to the nearest 8,000 bits. This commonly occurs in the following situations:
+ The underlying content stream changes the primary manifest
+ New sessions are created with different variants than existing sessions
+ Content stream bitrates are inconsistent across playback sessions
#### Harvest job bandwidth variance
For harvest jobs, MediaTailor uses a 15% bandwidth variance threshold when matching ads to content streams. If there is a difference of 15% or more between the bandwidth of the live stream and the bandwidth of the harvested HLS file, the ad will be transcoded again. This can result in NEW\$1CREATIVE skipping during the transcoding process.
This behavior commonly occurs when:
+ The same pre-transcoded ads are used for both live streaming and VOD content
+ The harvested content has different encoding parameters than the original live stream
+ Bandwidth differences exceed the 15% threshold between live and harvested content
### Creative ID conflicts
When MediaTailor encounters a different creative ID for a media file that was already transcoded, the following sequence occurs:
1. The ad is skipped with reason NEW\$1CREATIVE
1. This leads to an unnecessary transcoding attempt
1. The creative is marked as DUPLICATE\$1TRANSCODE or COPY\$1DEDUP
**Note**
MediaTailor does not expire or delete transcoded ads. We store them in a MediaTailor-owned S3 bucket indefinitely.
## Resolution steps
To resolve NEW\$1CREATIVE ad skipping issues:
1. Verify that your ad decision server returns consistent creative IDs for the same ad content.
1. Check that your content stream maintains consistent bitrates and variant sets.
1. Consider implementing ad prefetching to ensure ads are transcoded before playback. For more information, see [Prefetching ads](prefetching-ads.md).
1. For persistent issues, contact [AWS Support](https://aws.amazon.com/premiumsupport/) for additional troubleshooting assistance.
## Monitoring NEW\$1CREATIVE patterns
Use this CloudWatch Logs Insights query to analyze patterns in NEW\$1CREATIVE ad skipping:
```
fields @timestamp, sessionId, creativeId, skipReason, MediaFileSourceUrl
| filter skipReason = "NEW_CREATIVE"
| stats count() by creativeId, MediaFileSourceUrl
| sort count desc
| limit 50
```
# MediaTailor ADS timeout ad skipping troubleshooting
When ads are skipped with `ADS_TIMEOUT` or related reasons, you have connectivity or performance issues with your ad decision server. AWS Elemental MediaTailor requires reliable communication with your ADS to successfully insert ads. This troubleshooting guide explains how to identify and resolve these connectivity issues.
## Common ADS connectivity issues
Common ADS connectivity issues include the following:
+ Ad decision server not accessible from MediaTailor
+ ADS not responding within the configured timeout period
+ ADS unable to handle request volume during peak periods
+ Network connectivity issues between MediaTailor and your ADS
## Resolution steps
To resolve ADS timeout issues:
1. Verify that your ad decision server is accessible from MediaTailor.
1. Check that your ADS responds within the configured timeout period.
1. Ensure your ADS can handle the request volume during peak periods.
1. Consider implementing a fallback ad strategy for when your primary ADS is unavailable.
## Monitoring ADS performance
Set up CloudWatch alarms for the `AdDecisionServer.Timeouts` metric to proactively detect ADS connectivity issues.
# MediaTailor VAST parsing ad skipping troubleshooting
When ads are skipped with `VAST_PARSING_ERROR` or `MEDIA_FILE_UNAVAILABLE`, you have issues with your VAST responses or ad media files. AWS Elemental MediaTailor requires properly formatted VAST responses and accessible media files for successful ad insertion. This troubleshooting guide explains how to identify and resolve these issues.
## Common VAST issues
Common VAST issues include the following:
+ VAST response format not compliant with VAST specification
+ Media file URLs in VAST response not publicly accessible
+ Special characters not properly encoded in VAST XML
+ VAST response missing required media files or formats
## Resolution steps
To resolve VAST parsing issues:
1. Validate your VAST response format against the VAST specification.
1. Ensure all media file URLs in the VAST response are publicly accessible.
1. Check for proper encoding of special characters in your VAST XML.
1. Verify that your VAST response includes media files in formats compatible with MediaTailor.
## VAST wrapper troubleshooting
For issues with `INVALID_VAST_WRAPPER_AD` or `REJECTED_REPLICA_VAST`:
+ Validate VAST wrapper responses against the VAST specification
+ Ensure all wrapper elements are properly formatted and contain valid VASTAdTagURI
+ Check ad server configuration for duplicate content detection policies
+ Ensure VAST responses contain unique creative content within the same session
# MediaTailor duration mismatch ad skipping troubleshooting
When ads are skipped with `AVAIL_DURATION_EXCEEDED`, `LEFTOVER_AVAIL_EXCEEDED_THRESHOLD`, or format-related reasons, you have duration or format compatibility issues. AWS Elemental MediaTailor requires proper duration formatting and matching between ad content and available ad break time. This troubleshooting guide explains how to identify and resolve these duration-related issues.
## Common duration issues
Common duration issues include the following:
+ Ads longer than available ad break duration
+ Incorrect ad break markers in content signaling wrong duration
+ Personalization threshold not met for ad insertion
+ Incorrect duration format in EXT-X-CUE-OUT tags
## Duration format requirements
The EXT-X-CUE-OUT tag duration parameter must be formatted as an integer value, not as an ISO 8601 duration format.
**Duration format requirements**
| Format | Example | Status |
| --- | --- | --- |
| Integer (Correct) | 32 | Supported - represents 32 seconds |
| Decimal (Correct) | 30.000 | Supported - represents 30 seconds |
| ISO 8601 (Incorrect) | PT32S | Not supported - causes insertion failures |
## Resolution steps
To resolve duration mismatch issues:
1. Ensure your ADS returns ads that fit within the available ad break duration.
1. Check that your ad break markers in the content correctly signal the intended duration.
1. Verify that EXT-X-CUE-OUT duration parameters use integer format.
1. Consider adjusting the personalization threshold if appropriate for your use case.
# MediaTailor session variable ad skipping troubleshooting
Session variables play a critical role in ad targeting and selection in AWS Elemental MediaTailor. Incorrect session variable configuration is a common cause of ad skipping issues. This comprehensive troubleshooting guide explains how to identify and resolve session variable problems that can prevent successful ad insertion.
## Common session variable issues
Common session variable issues include the following:
+ **Missing required variables**: Your ad decision server might require specific variables that aren't being provided.
+ **Incorrect variable syntax**: Variables must use the correct syntax (for example, `[session.id]` instead of `${session.id}`).
+ **URL encoding issues**: Special characters in variable values might need proper URL encoding.
+ **Inconsistent player parameters**: Player parameters must be consistently passed across sessions.
+ **Dynamic variable resolution failures**: Variables that can't be resolved are replaced with empty strings.
+ **SCTE-35 UPID parsing issues**: Problems with segmentation UPID processing can cause session variable resolution failures.
## Verifying session variable resolution
To verify that your session variables are being properly resolved:
1. Enable debug logging for your MediaTailor configuration
1. Check the `MediaTailor/AdDecisionServerInteractions` log group for the actual ADS request URLs
1. Verify that all variables in the template URL have been replaced with appropriate values
1. Look for any variables that were replaced with empty strings, which may indicate resolution failures
## SCTE-35 UPID parsing troubleshooting
Problems with SCTE-35 segmentation UPID processing can cause session variable issues:
+ **Format requirements:** UPID must have `segmentation_upid_type` of 12 and include `format_identifier` for proper processing
+ **Parsing rules:** Decoded UPID can contain colon delimiters for multiple values. The number of template variables and decoded UPID tokens must be equal
+ **Invalid formats:** Avoid double colons with no values (e.g., `::` or `:46175218::4053`) as these cause parsing failures
# MediaTailor ad skipping monitoring and alerts
Proactive monitoring helps you detect and resolve ad skipping issues before they significantly impact your revenue. AWS Elemental MediaTailor provides comprehensive metrics and logging capabilities that enable effective monitoring of ad insertion performance. This guide explains how to set up effective monitoring for ad skipping issues.
## Key CloudWatch metrics to monitor
Set up CloudWatch alarms for these key MediaTailor metrics:
+ `AdDecisionServer.Ads.Skipped` - Count of skipped ads
+ `AdDecisionServer.Timeouts` - Count of ADS timeouts
+ `Avail.FilledDuration` - Duration of filled ad breaks
+ `Avail.SlateOnly` - Count of ad breaks filled with slate only
## Advanced CloudWatch Logs Insights queries
Use these specialized queries for detailed troubleshooting:
### Comprehensive session analysis
For detailed analysis of ad insertion behavior for a specific session:
```
fields @timestamp, sessionId, eventType, creativeId, skipReason, adBreakIndex
| filter sessionId = "your-session-id-here"
| filter eventType in ["FILLED_AVAIL", "SKIPPED_AVAIL", "MAKING_ADS_REQUEST"]
| sort @timestamp asc
| limit 100
```
### Finding Creative IDs
To identify Creative IDs from FILLED\$1AVAIL events:
```
fields @timestamp, sessionId, eventType
| filter sessionId like /sessionId/ and eventType!='BEACON_FIRED'
| sort @timestamp desc
```
**Note**
Replace `sessionId` with the actual session ID you're investigating.
# MediaTailor ad skipping prevention best practices
Implementing these best practices helps prevent ad skipping issues before they occur, ensuring better ad insertion performance and revenue protection with AWS Elemental MediaTailor. These proactive measures address the most common causes of ad skipping and help maintain consistent ad delivery.
## Proactive measures
+ **Implement ad prefetching**: Use MediaTailor's prefetch feature to ensure ads are transcoded before playback. See [Prefetching ads](prefetching-ads.md) for implementation details
+ **Maintain consistent creative IDs**: Ensure your ad decision server uses consistent creative IDs for the same ad content across sessions
+ **Ensure proper duration formatting**: Use integer values for EXT-X-CUE-OUT duration parameters instead of ISO 8601 format
+ **Configure VOD optimization**: Set maxConcurrentAdsRequests for VOD streams with multiple ad breaks to reduce server load
+ **Optimize ADS performance**: Configure your ad decision server to respond quickly and handle peak traffic volumes
## Implementation guidelines
+ **Implement proper error handling**: Configure slate content to fill ad breaks when ads cannot be inserted
+ **Test thoroughly**: Validate your ad insertion workflow across different devices and network conditions
+ **Implement fallback strategies**: Configure backup ad sources or default ads for when primary ad sources fail
+ **Monitor transcoding patterns**: Monitor CloudWatch logs for transcoding efficiency and contact [AWS Support](https://aws.amazon.com/premiumsupport/) if you notice patterns that indicate transcoding issues
# MediaTailor ad skipping reference guide
This section provides comprehensive reference information about ad skip reasons and links to related documentation for AWS Elemental MediaTailor. Use this reference guide to understand the specific meanings of different skip reasons and find additional troubleshooting resources.
## Complete ad skip reasons reference
MediaTailor logs specific reasons why ads are skipped in the `FILLED_AVAIL` event log message from the `MediaTailor/AdDecisionServerInteractions` log group.
**Complete ad skip reasons**
| Skip reason | Description |
| --- | --- |
| NEW\$1CREATIVE | The ad has not been transcoded yet. This occurs when MediaTailor encounters a new ad creative that requires transcoding before insertion. |
| PROFILE\$1NOT\$1FOUND | The MediaConvert transcode profile associated with the session's configuration does not exist, preventing ad preparation. |
| TRANSCODE\$1ERROR | The ad transcode process encountered an error and failed to complete. |
| TRANSCODE\$1IN\$1PROGRESS | The ad transcode is still in progress and not yet ready for insertion. |
| INTERNAL\$1ERROR | An internal MediaTailor error occurred while handling the ad, preventing insertion. |
| AVAIL\$1DURATION\$1EXCEEDED | The ad does not fit within the remaining duration of the ad break. |
| LEFTOVER\$1AVAIL\$1EXCEEDED\$1THRESHOLD | The cumulative duration of all ads that could have been inserted does not meet the personalization threshold configured for the session. |
| VAST\$1PARSING\$1ERROR | The VAST response from the ad decision server contains errors or is malformed. |
| ADS\$1TIMEOUT | The ad decision server did not respond within the configured timeout period. |
| MEDIA\$1FILE\$1UNAVAILABLE | The ad media files specified in the VAST response are not accessible. |
| SESSION\$1INITIALIZATION\$1FAILED | The MediaTailor session failed to initialize properly, often due to incorrect session variables. |
| EARLY\$1CUE\$1IN | The ad break ended earlier than expected due to an early cue-in signal, preventing the ad from being fully inserted. |
| NO\$1VARIANT\$1MATCH | The ad creative does not have a variant that matches the content stream's encoding parameters (bitrate, resolution, codec). |
| NO\$1MODEL\$1CREATIVE\$1MATCH | The ad creative does not match the expected model or format requirements for the current playback configuration. |
| REJECTED\$1REPLICA\$1VAST | The VAST response was rejected due to replica or duplicate content detection policies. |
| INVALID\$1VAST\$1WRAPPER\$1AD | The VAST wrapper ad contains invalid or malformed wrapper elements that prevent successful ad insertion. |
| IMPORT\$1ERROR | An error occurred during the ad import process, preventing the ad from being processed for insertion. |
| IMPORT\$1IN\$1PROGRESS | The ad import process is currently in progress and has not completed yet. |
## Related resources
For more information on troubleshooting ad skipping issues, refer to these related topics:
+ [MediaTailor dynamic ad variables for ADS requests](variables.md) - Comprehensive guide to dynamic ad variables in MediaTailor
+ [Prefetching ads](prefetching-ads.md) - How to implement ad prefetching to prevent transcoding-related skipping
+ [Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics](monitoring-cloudwatch-metrics.md) - Monitoring MediaTailor with CloudWatch metrics
+ [Viewing AWS Elemental MediaTailor logs](monitoring-through-logs.md) - How to view and analyze MediaTailor logs
+ [Troubleshooting MediaTailor event flow issues](troubleshooting-event-flow.md) - Understanding the ad insertion event flow