# Troubleshoot issues with MediaTailor and CDN integration
Troubleshoot CDN integration

This comprehensive troubleshooting guide covers common content delivery network (CDN) integration issues across all AWS Elemental MediaTailor implementations including server-side ad insertion (SSAI), channel assembly, and AWS Elemental MediaPackage integration. When your CDN and MediaTailor integration experiences problems, use this systematic diagnostic approach to quickly identify root causes and implement validated solutions.

This guide applies to all MediaTailor CDN integrations regardless of your specific workflow. For issues specific to particular services or workflows, see the related troubleshooting sections referenced at the end of this guide.

**Before you begin:** Have these items ready for efficient troubleshooting:
+ Sample playback URLs that demonstrate the issue
+ CDN access logs from the time period when issues occurred
+ MediaTailor configuration name and AWS Region
+ Player type and version (for example, HLS.js 1.4.0, Video.js 8.0)
+ Device and browser information where issues occur

**Related topics:**
+ For operational setup and troubleshooting preparation, see [Troubleshoot CDN integration](#cdn-troubleshooting)
+ For log analysis and error code reference, see [CDN integration log analysis reference](cdn-log-error-reference.md)
+ For escalation and getting additional help, see [Get CDN integration support](cdn-get-help.md)

# Diagnostic checklist for MediaTailor and CDN integrations
Quick diagnostic checklist

AWS Elemental MediaTailor content delivery network (CDN) integration problems can manifest in various ways. Use this checklist to quickly identify the type of issue you're experiencing:

1. **Is the issue affecting all viewers or specific viewers?**
   + All viewers → Likely CDN or MediaTailor configuration issue
   + Specific viewers → Likely personalization or targeting issue

1. **Are manifests loading correctly?**
   + No → CDN routing or MediaTailor connectivity issue
   + Yes, but wrong content → Caching or personalization issue

1. **Are segments loading correctly?**
   + Content segments fail → Origin connectivity issue
   + Ad segments fail → Ad delivery or transcoding issue

1. **Are ads being inserted correctly?**
   + No ads appear → Check ADS connectivity and configuration
   + Wrong ads appear → Check ad targeting parameters and personalization
   + Ads fail to play → Check ad transcoding and segment availability

1. **Is playback smooth and uninterrupted?**
   + Buffering issues → Check CDN cache performance and origin response times
   + Playback errors → Check manifest syntax and segment availability
   + Ad transition issues → Check ad break timing and segment alignment

1. **Are there specific error codes or messages?**
   + HTTP 4xx errors → Check CDN routing and configuration
   + HTTP 5xx errors → Check origin server and MediaTailor service health
   + Player-specific errors → Check manifest format and player compatibility

**Next steps based on your diagnosis:**

CDN configuration issues  
For detailed CDN routing and caching troubleshooting, see [Troubleshoot issues with MediaTailor and CDN integration](cdn-troubleshooting.md).

Manifest and playback issues  
For manifest validation and playback troubleshooting, see [CDN integration testing procedures](cdn-testing-procedures.md).

Ad insertion and targeting issues  
For ad-specific troubleshooting including ADS connectivity and ad delivery, see your workflow-specific troubleshooting documentation.

Performance and monitoring issues  
For performance analysis and monitoring setup, see [Monitor MediaTailor CDN operations and performance](cdn-monitoring.md).

Log analysis and error codes  
For detailed log analysis and error code reference, see [CDN integration log analysis and error code reference for MediaTailor](cdn-log-error-reference.md).

Testing and validation  
For comprehensive testing procedures, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md).

If you need immediate assistance or cannot resolve the issue using the linked resources, see [Get support and troubleshooting help for CDN and MediaTailor integrations](cdn-get-help.md) for escalation procedures.

# CDN integration testing procedures
Integration testing

Proper testing is essential before deploying your MediaTailor CDN integration to production. These testing procedures help identify configuration issues, performance problems, and compatibility issues across different devices and platforms.

## Basic integration validation


Perform these fundamental tests to verify your CDN integration is working correctly:

1. **Test manifest delivery**:
   + Request a manifest through your CDN and verify it returns a valid response
   + Verify the manifest contains expected content and ad insertion points
   + Check that manifest URLs use your CDN domain, not the origin
   + Validate manifest syntax using HLS or DASH validation tools

1. **Verify URL rewriting**:
   + Check that content segment URLs in manifests point to your CDN domain
   + Verify ad segment URLs point to your CDN domain
   + Ensure all relative URLs are properly resolved

1. **Test content playback**:
   + Play content through a video player and verify smooth playback
   + Verify both content and ads play without interruption
   + Check for proper transitions between content and ads
   + Test seeking and scrubbing functionality

1. **Validate CDN routing**:
   + Monitor CDN access logs to ensure requests are routed correctly
   + Verify cache hit/miss patterns are as expected
   + Check that origin requests only occur for cache misses

## Advanced testing procedures


Perform these additional tests for comprehensive validation:

1. **Cross-platform compatibility testing**:
   + Test on multiple devices (desktop, mobile, tablet, smart TV)
   + Verify compatibility across different browsers
   + Test with various video players (HLS.js, Video.js, native players)
   + Validate on different operating systems

1. **Performance testing**:
   + Measure manifest request response times (target: <100ms for cached)
   + Test segment loading performance across different bitrates
   + Verify startup time meets performance targets
   + Test under various network conditions

1. **Ad tracking validation**:
   + Verify ad tracking beacons fire correctly
   + Check ad analytics data for accuracy
   + Test impression and completion tracking
   + Validate click-through functionality

1. **Error condition testing**:
   + Test behavior when origin is temporarily unavailable
   + Verify graceful handling of malformed requests
   + Test CDN failover scenarios
   + Validate error message clarity and usefulness

## Create a test environment


Set up a test environment that mirrors your production configuration for comprehensive validation:

1. Set up separate CDN distributions for testing:
   + Create test CDN distributions with the same cache behaviors as production
   + Configure test origins that mirror your production setup
   + Use separate domain names to avoid conflicts with production traffic

1. Create test MediaTailor configurations:
   + Set up test playback configurations with the same settings as production
   + Configure test ad decision server endpoints
   + Use test ad content that matches your production ad formats

1. Implement systematic testing processes:
   + Create testing checklists for configuration changes
   + Document test procedures for your team
   + Set up automated testing where possible

## Test across multiple scenarios


Validate your integration across different scenarios and conditions to ensure comprehensive coverage:

1. Test with multiple player types and devices:
   + Test with different video players (web, mobile, connected TV)
   + Validate across different operating systems and browsers
   + Test on various network conditions and connection speeds

1. Create automated testing scripts:
   + Automate manifest request validation
   + Create scripts to test ad insertion scenarios
   + Implement performance testing for high-traffic scenarios

1. Validate ad targeting and personalization:
   + Test with different user profiles and targeting parameters
   + Validate ad decision server integration
   + Test fallback scenarios when ads are unavailable

## Testing tools and techniques


Use these tools and techniques for effective testing:

Browser developer tools  
Use Network tab to inspect HTTP requests and responses  
Monitor console for JavaScript errors and warnings  
Verify response headers and caching behavior  
Check timing information for performance analysis

Command-line testing  
Use curl to test specific URLs and inspect headers:  

```
curl -I "https://your-cdn-domain.com/path/to/manifest.m3u8"
```
Use wget for download testing and timing analysis  
Employ tools like httpie for more readable HTTP testing

Video player testing  
Test with multiple player implementations  
Use player debug modes to inspect internal behavior  
Monitor player events and error callbacks  
Validate adaptive bitrate switching behavior

CDN analytics and monitoring  
Monitor real-time CDN metrics during testing  
Review access logs for request patterns  
Use CDN-specific testing tools when available  
Set up temporary alerts for testing validation

For additional comprehensive testing methodologies and systematic validation approaches, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md).

# Troubleshoot CDN manifest 404 errors for MediaTailor
Manifest 404 errors

AWS Elemental MediaTailor content delivery network (CDN) manifest 404 errors are a common integration issue that prevents playback from starting. This section provides step-by-step troubleshooting for manifest delivery failures. 

Multivariant playlist, media playlist, or MPD requests return 404 errors  
**Quick fix (try first):**  

1. Verify the MediaTailor configuration name in your URL matches exactly (case-sensitive)

1. Test the manifest URL directly against MediaTailor without CDN: `curl -v "https://your-emt-endpoint.mediatailor.region.amazonaws.com/v1/master/hls/config-name/master.m3u8"`

1. If direct test works, check CDN routing rules for manifest requests
**If quick fix doesn't work:**  
**Symptoms:** Players fail to start playback, manifest requests return HTTP 404 errors in CDN logs.  
**Example error messages:**  
+ Browser console: `"Failed to load resource: the server responded with a status of 404 (Not Found)"`
+ Player error: `"MANIFEST_LOAD_ERROR"` or `"NETWORK_ERROR"`
+ CDN logs: `GET /v1/master/hls/example-config/master.m3u8 404`
**Resolution:**  
Verify that your CDN routing rules are correctly configured to forward multivariant playlist, media playlist, and MPD requests to MediaTailor.  
Check that the MediaTailor configuration exists and is correctly set up.  
Ensure your CDN behavior patterns match the expected manifest request paths (for example, `*.m3u8`, `*.mpd`).

# Diagnose CDN manifest delivery issues and errors for MediaTailor
Manifest delivery issues

AWS Elemental MediaTailor content delivery network (CDN) manifest delivery problems can prevent proper ad insertion and playback. If viewers receive incorrect or inconsistent ads in multivariant playlists, media playlists, or MPDs:

1. Check for cached manifests:
   + Verify TTL settings are set to 0 for all multivariant playlist, media playlist, and MPD paths
   + Confirm that your CDN isn't caching multivariant playlists, media playlists, or MPDs despite TTL settings
   + Check CDN logs for cache status - manifest requests should show `Miss` or `RefreshHit`, not `Hit`

1. Verify CDN routing configuration:
   + Confirm manifest requests are being routed to MediaTailor endpoints, not cached or served from origin
   + Check that CDN behavior patterns correctly match manifest paths (\$1.m3u8, \$1.mpd)
   + Verify query parameters are being forwarded to MediaTailor for personalization
   + Test manifest URLs directly against MediaTailor to isolate CDN vs service issues

1. Check header forwarding configuration:
   + Verify required headers are being forwarded (see [Required headers for MediaTailor CDN integration](cdn-configuration.md#cdn-required-headers))
   + Confirm User-Agent header is forwarded for device-specific ad targeting
   + Check that X-Forwarded-For header is forwarded for geo-targeting
   + Ensure Accept-Encoding header is forwarded for compression support

1. Validate manifest content and structure:
   + Check that manifests contain expected ad insertion markers (EXT-X-CUE-OUT/IN for HLS)
   + Verify segment URLs in manifests use your CDN domain, not origin domains
   + Confirm ad segments are properly inserted and accessible
   + Test manifest syntax using validation tools (ffprobe for HLS, mp4box for DASH)

1. Test different scenarios:
   + Test with different session IDs to verify personalization is working
   + Test from different geographic locations to verify geo-targeting
   + Test with different User-Agent strings to verify device targeting
   + Compare manifest responses with and without CDN to identify differences

**Additional troubleshooting resources:**
+ For detailed CDN caching configuration, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md)
+ For comprehensive CDN routing setup, see [Set up CDN routing behaviors for MediaTailor](cdn-routing-behaviors.md)
+ For header forwarding requirements, see [Required headers for MediaTailor CDN integration](cdn-configuration.md#cdn-required-headers)
+ For log analysis and error codes, see [CDN integration log analysis and error code reference for MediaTailor](cdn-log-error-reference.md)
+ For testing procedures and validation, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md)

**Success criteria:** When resolved, players should start playback normally and ads should appear as expected. Manifest requests should return HTTP 200 status codes in CDN logs, and manifests should contain properly personalized ad content.

# Troubleshoot CDN segment delivery and loading issues for MediaTailor
Segment delivery issues

AWS Elemental MediaTailor content delivery network (CDN) segment delivery problems can cause buffering and playback interruptions. If players can't load segments or experience buffering:

1. Check CDN routing rules:
   + Verify content segments are being routed to the correct origin
   + Confirm ad segments are being routed to the correct MediaTailor ad storage location
   + Check that segment file extensions match your CDN behavior patterns
   + Verify that segment URLs in manifests use the correct CDN domain
   + For detailed instructions on setting up routing and behavior path patterns, see [Set up CDN routing behaviors for MediaTailor](cdn-routing-behaviors.md)

1. Verify CORS configuration:
   + For web players, ensure your CDN is passing through or properly setting CORS headers
   + Test with browser developer tools to identify CORS-related errors
   + Verify that preflight OPTIONS requests are handled correctly

1. Test segment accessibility and performance:
   + Test individual segment URLs directly to verify they're accessible
   + Check segment response times and identify performance bottlenecks
   + Verify segment file sizes are appropriate for your bandwidth targets
   + Test segment loading from different geographic locations

1. Validate CDN caching behavior for segments:
   + Verify content segments have appropriate TTL settings (typically longer than manifests)
   + Check that ad segments are cached appropriately based on personalization requirements
   + Monitor cache hit ratios for both content and ad segments
   + Ensure cache keys don't include unnecessary parameters that reduce cache efficiency

1. Check origin server connectivity and health:
   + Verify origin servers are responding correctly to segment requests
   + Check origin server capacity and response times under load
   + Validate that origin servers have the expected segment files available
   + Test origin failover scenarios if multiple origins are configured

1. Troubleshoot ad segment specific issues:
   + Verify ad segments are properly transcoded and available in MediaTailor
   + Check that ad segment URLs are correctly generated in manifests
   + Test ad segment loading with different ad targeting parameters
   + Monitor for ad transcoding delays that might cause segment unavailability

1. Validate player compatibility and behavior:
   + Test segment loading with different player types and versions
   + Check player buffer settings and segment request patterns
   + Verify player error handling for failed segment requests
   + Test adaptive bitrate switching and segment selection logic

**Additional troubleshooting resources:**
+ For CDN routing and behavior configuration, see [Set up CDN routing behaviors for MediaTailor](cdn-routing-behaviors.md)
+ For CDN caching optimization, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md)
+ For CORS configuration guidance, see [CDN integration security best practices for MediaTailor](cdn-security-best-practices.md)
+ For performance monitoring and analysis, see [Monitor MediaTailor CDN operations and performance](cdn-monitoring.md)
+ For comprehensive testing procedures, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md)
+ For log analysis and error diagnosis, see [CDN integration log analysis and error code reference for MediaTailor](cdn-log-error-reference.md)

**Success criteria:** When resolved, players should load segments smoothly without buffering interruptions. Segment requests should return HTTP 200 status codes with appropriate response times, and both content and ad segments should be accessible and properly cached.

# Fix CDN session management and tracking issues for MediaTailor
Session management issues

AWS Elemental MediaTailor content delivery network (CDN) session management is critical for proper ad personalization and tracking. If you encounter session-related errors or inconsistent behavior across requests:

1. Check for session ID consistency:
   + Verify that your player maintains the same session ID across all requests for a single playback session
   + Check CDN logs to confirm session IDs are being forwarded correctly
   + Ensure session IDs are properly URL-encoded in query parameters
   + Use CloudWatch Logs to verify session ID consistency across requests (see validation steps below)

1. Validate session initialization:
   + Confirm that the first manifest request successfully creates a session
   + Check for proper session parameter forwarding (for example, `aws.sessionId`)
   + Verify session initialization using debug logs (see debug log setup below)

1. Enable debug logging for detailed session troubleshooting:
   + **For server-side reporting:** Add `?aws.logMode=DEBUG` to your playback request:

     ```
     GET <mediatailorURL>/v1/master/<hashed-account-id>/<origin-id>/<asset-id>?aws.logMode=DEBUG
     ```
   + **For client-side reporting:** Include `"logMode": "DEBUG"` in your session initialization request body
   + **Important:** The `DEBUG` value is case-sensitive
   + Maximum of 10 active debug sessions allowed simultaneously

1. Use CloudWatch Logs queries to validate session behavior:
   + **Verify debug session is active:**

     ```
     fields @timestamp, @message
     | filter sessionId = "your-session-id-here"
     | filter eventType = "SESSION_INITIALIZED" # client-side reporting
     or mediaTailorPath like "/v1/master" # server-side reporting HLS
     or mediaTailorPath like "/v1/dash" # server-side reporting DASH
     ```
   + **View all events for a session:**

     ```
     fields @timestamp, @message, eventType, mediaTailorPath
     | filter sessionId = "your-session-id-here"
     | sort @timestamp asc
     ```
   + **Check manifest generation for a session:**

     ```
     fields @timestamp, responseBody, @message
     | filter mediaTailorPath like "/v1/master/" and eventType = "GENERATED_MANIFEST" and sessionId = "your-session-id-here"
     ```

1. Test session parameter forwarding through CDN:
   + Test manifest requests with session parameters directly against MediaTailor (bypassing CDN)
   + Compare session behavior with and without CDN to identify forwarding issues
   + Verify CDN query parameter forwarding configuration includes session-related parameters
   + Check that CDN doesn't cache responses that should be session-specific

**Common session error messages:**
+ `ConflictException` (HTTP 409) - Multiple simultaneous playlist requests for the same session. **Solution:** Ensure your player requests playlists one at a time according to HLS specification
+ `NotFoundException` (HTTP 404) - Session is unavailable or configuration doesn't exist. **Solution:** Check your configuration validity and reinitialize the session
+ `BadRequestException` (HTTP 400) - Invalid session ID or improperly formatted request. **Solution:** Verify request formatting and session ID validity

**Additional troubleshooting resources:**
+ For complete debug logging setup and field reference, see [Generating AWS Elemental MediaTailor debug logs](debug-log-mode.md)
+ For CloudWatch Logs query examples and log analysis, see [Writing AWS Elemental MediaTailor logs directly to Amazon CloudWatch Logs](monitoring-cw-logs.md)
+ For CDN query parameter forwarding configuration, see [Set up CDN routing behaviors for MediaTailor](cdn-routing-behaviors.md)
+ For comprehensive error code reference, see [Troubleshooting playback from MediaTailor](playback-errors.md)

**Success criteria:** When resolved, sessions should initialize correctly, maintain consistent session IDs across requests, and debug logs should show proper `SESSION_INITIALIZED` events and manifest generation without errors.

# Resolve CDN ad break timing and synchronization issues for MediaTailor
Ad break timing issues

AWS Elemental MediaTailor content delivery network (CDN) ad break timing must be precisely synchronized with content markers. If ads appear at incorrect times or ad break timing is inconsistent:

1. Verify ad break markers in content:
   + Check that SCTE-35 markers are properly placed in your origin content
   + Verify ad break duration matches actual ad content length
   + Confirm that ad break timing aligns with content boundaries
   + Validate SCTE-35 marker format and timing accuracy in your origin manifests
   + Test ad break markers with different content types (live vs VOD)

1. Check CDN caching impact on timing:
   + Ensure manifest TTL is set to 0 to prevent timing drift
   + Verify that time-sensitive parameters are not being cached
   + Check for clock synchronization issues between the content source, MediaTailor, and the CDN
   + Monitor for timing drift in long-running live streams
   + Verify CDN edge server time synchronization with NTP

1. Validate SCTE-35 marker implementation:
   + Verify EXT-X-DATERANGE tags include proper SCTE35-OUT and DURATION specifications
   + Check for paired SCTE35-OUT and SCTE35-IN markers when using explicit cue-in timing
   + Validate START-DATE timestamps align with actual content timing
   + Test different SCTE-35 marker formats (duration-based vs paired markers)

1. Test ad break timing across different scenarios:
   + Compare ad break timing with direct MediaTailor requests vs CDN requests
   + Test timing consistency across different CDN edge locations
   + Verify ad break timing with different player types and buffering behaviors
   + Monitor timing accuracy during peak traffic periods

1. Debug timing issues using logs and monitoring:
   + Enable debug logging to track ad break processing timing
   + Monitor CloudWatch metrics for ad insertion timing patterns
   + Check CDN logs for timing-related request patterns
   + Use player debugging tools to verify ad break timing from client perspective

**Expected timing tolerances:**
+ Ad break timing should align with SCTE-35 markers in your content
+ Ad duration should match the duration specified in your ad decision server response
+ Clock synchronization between content source, MediaTailor, and CDN should be within 1 second
+ SCTE-35 marker timing should be accurate to within 100ms of actual content timing

**Additional troubleshooting resources:**
+ For SCTE-35 marker format and implementation, see [Integrating a content source for MediaTailor ad insertion](integrating-origin.md)
+ For debug logging setup and timing analysis, see [Generating AWS Elemental MediaTailor debug logs](debug-log-mode.md)
+ For CDN caching configuration and timing impact, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md)
+ For comprehensive testing procedures including timing validation, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md)
+ For monitoring ad insertion timing and performance, see [Monitor MediaTailor CDN operations and performance](cdn-monitoring.md)

**Success criteria:** When resolved, ad breaks should appear at precisely the times specified by SCTE-35 markers, with consistent timing across all CDN edge locations and player types. Debug logs should show accurate ad break processing timing without drift or synchronization errors.

# Optimize CDN performance and resolve latency issues for MediaTailor
Performance and latency issues

AWS Elemental MediaTailor content delivery network (CDN) integration performance directly impacts viewer experience and ad delivery quality. If you experience slow response times or performance degradation:

## Performance measurement techniques


Before troubleshooting performance issues, establish baseline measurements and ongoing monitoring:

1. Measure key performance metrics:
   + **Response times:** Manifest requests should complete within 200ms, segment requests within 100ms
   + **Cache hit ratios:** Content segments >95%, ad segments >90%
   + **Origin request volume:** Should be less than 5% of total requests when cache is optimized
   + **Time to first frame:** Initial playback should start within 2-3 seconds

1. Use performance measurement tools:
   + **CDN analytics dashboards:** Monitor cache performance, response times, and error rates
   + **CloudWatch metrics:** Track MediaTailor service metrics including GetManifest.Latency
   + **Browser developer tools:** Measure client-side performance and network timing
   + **Command-line tools:** Use curl with timing options to measure specific requests

1. Implement continuous monitoring:
   + Set up automated performance alerts for response time degradation
   + Monitor performance across different geographic regions
   + Track performance during peak traffic periods
   + Compare performance metrics before and after configuration changes

**Performance measurement resources:**
+ For comprehensive performance monitoring setup, see [Monitor MediaTailor CDN operations and performance](cdn-monitoring.md)
+ For performance testing procedures, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md)
+ For CloudWatch metrics and monitoring, see [Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics](monitoring-cloudwatch-metrics.md)

## CDN cache performance issues


Cache performance problems are among the most common CDN integration issues. These problems affect all MediaTailor implementations and can significantly impact viewer experience and costs.

**Low cache hit ratio**  
**Symptoms**: High origin request volume, increased latency, higher bandwidth costs, poor viewer experience  
**Target values**:  
+ Content segments: 95% or higher cache hit ratio
+ Ad segments: 90% or higher cache hit ratio
+ Manifests: Varies by implementation (personalized manifests should not be cached)
**Common causes**:  
+ Incorrect TTL settings for different content types
+ Cache key configuration includes unnecessary query parameters
+ Cache-control headers from origin not properly configured
+ Frequent cache invalidations or purges
+ Geographic distribution issues (content not cached at edge locations)
**Solutions**:  

1. Review and optimize TTL settings:
   + Content segments: Set TTL to match segment duration or longer
   + Ad segments: Set TTL to 24 hours or longer for reusable ads
   + Static assets: Set TTL to 24 hours or longer

   For comprehensive TTL recommendations and caching optimization strategies, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md).

1. Optimize cache key configuration:
   + Remove unnecessary query parameters from cache keys
   + Ensure only content-affecting parameters are included
   + Normalize parameter order and case sensitivity

1. Verify origin cache-control headers are properly set

1. Implement origin shield (or equivalent CDN functionality) for high-traffic implementations. Origin shield functionality is available across major CDNs but might have different names (such as CloudFront Origin Shield, Fastly Shield, Cloudflare Argo Tiered Cache). If your CDN doesn't offer this functionality, it can be enabled in MediaTailor when you contact [AWS Support](https://aws.amazon.com/premiumsupport/).

1. Review cache invalidation strategies and reduce unnecessary purges
**Validation steps**:  

1. Monitor cache hit ratios using CDN analytics dashboards

1. Test specific URLs with curl to verify cache headers

1. Compare origin request volume before and after changes

**High origin request volume**  
**Symptoms**: Unexpectedly high number of requests reaching MediaTailor origin, increased origin server load, higher costs  
**Expected pattern**: Origin requests should be less than 5% of total viewer requests when cache hit ratios are optimal  
**Common causes**:  
+ Cache misses due to low TTL values
+ Cache key fragmentation (too many unique cache keys)
+ Geographic traffic spikes in regions without cached content
+ Frequent cache invalidations
**Solutions**:  

1. Analyze request patterns to identify cache miss causes

1. Optimize TTL settings based on content type and update frequency

1. Implement cache warming strategies for new content

1. Consider origin shield implementation (available across major CDNs with different names - see [Origin Shield implementation](cdn-advanced-optimization.md#origin-shield-optimization) for details)
**Alert threshold**: Set alerts when origin requests exceed 10% of total requests or increase by 50% over baseline

## Common HTTP error resolution


HTTP errors in CDN integrations often indicate configuration issues or service problems. These error patterns are consistent across all MediaTailor implementations.

**404 Not Found errors**  
**Symptoms**: Manifest or segment requests return HTTP 404, players fail to load content, "MANIFEST\$1LOAD\$1ERROR" in player logs  
**Common causes**:  
+ Incorrect CDN origin configuration (wrong MediaTailor endpoint URL)
+ Missing or incorrect cache behavior path patterns
+ URL rewriting issues in CDN configuration
+ MediaTailor configuration name or playback endpoint errors
+ Timing issues with live content (requesting future segments)
**Diagnostic steps**:  

1. Test the same URL directly against MediaTailor origin (bypass CDN)

1. Verify CDN origin configuration matches MediaTailor playback endpoint

1. Check CDN cache behavior path patterns and precedence

1. Review CDN access logs for request routing details

1. Validate MediaTailor configuration name and region settings
**Solutions**:  
+ Correct CDN origin configuration to match MediaTailor playback endpoint
+ Update cache behavior path patterns to properly route requests
+ Fix URL rewriting rules if applicable
+ Verify MediaTailor configuration exists and is active

**403 Forbidden errors**  
**Symptoms**: Requests return HTTP 403, access denied messages, authentication failures  
**Common causes**:  
+ Missing or incorrect query parameters required by MediaTailor
+ CDN not forwarding required headers or parameters
+ IP address restrictions or geographic blocking
+ Authentication token issues (if using signed URLs)
**Solutions**:  
+ Verify all required query parameters are included and forwarded
+ Check CDN configuration for header and parameter forwarding
+ Review IP restrictions and geographic settings
+ Validate authentication tokens and signing processes

**400 Bad Request errors**  
**Symptoms**: Requests return HTTP 400, malformed request errors, parameter validation failures  
**Common causes**:  
+ Malformed query parameters or URL encoding issues
+ Invalid parameter values or formats
+ Missing required parameters for specific MediaTailor features
+ URL length limitations exceeded
**Solutions**:  
+ Validate query parameter formats and URL encoding
+ Check parameter values against MediaTailor API requirements
+ Ensure all required parameters are included
+ Review URL length and consider parameter optimization

**5xx Server errors**  
**Symptoms**: Requests return HTTP 500, 502, 503, or 504 errors, intermittent service failures  
**Common causes**:  
+ MediaTailor service issues or capacity limitations
+ CDN origin connectivity problems
+ Timeout issues due to slow origin responses
+ Temporary service degradation
**Solutions**:  
+ Check AWS Service Health Dashboard for MediaTailor service status
+ Verify CDN origin connectivity and timeout settings
+ Implement retry logic with exponential backoff
+ Monitor MediaTailor CloudWatch metrics for service health
+ Contact AWS Support if issues persist

1. Measure baseline performance:
   + Test manifest request response times directly to MediaTailor (target: <200ms)
   + Measure CDN response times for manifest requests (target: <100ms for cache hits)
   + Check segment loading times from both origin and CDN

1. Analyze CDN performance:
   + Check cache hit ratios for content segments (target: >80% for popular content)
   + Verify origin shield (or equivalent CDN functionality) is enabled and configured in the same AWS Region as your origin. Different CDNs use different names for this functionality
   + Monitor CDN edge location performance and geographic distribution

**Performance benchmarks:**
+ Monitor manifest generation response times and compare against your baseline performance
+ CDN cache hits are significantly faster than origin requests
+ ADS response times should not cause manifest generation delays

**Additional troubleshooting resources:**
+ For comprehensive performance optimization strategies, see [Performance optimization guide for CDN and MediaTailor integrations](cdn-optimization.md)
+ For origin shield implementation details, see [Origin Shield implementation](cdn-advanced-optimization.md#origin-shield-optimization)
+ For CDN caching optimization, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md)
+ For performance monitoring and metrics, see [Monitor MediaTailor CDN operations and performance](cdn-monitoring.md)
+ For performance testing procedures, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md)

**Success criteria:** When resolved, response times should meet target benchmarks (manifests less than 200ms, segments less than 100ms), cache hit ratios should exceed 90% for most content types, and origin request volume should be less than 5% of total requests. Performance should be consistent across all geographic regions and device types.

# Fix CDN inconsistent behavior across devices and platforms for MediaTailor
Inconsistent device behavior

AWS Elemental MediaTailor content delivery network (CDN) integration should provide consistent ad delivery across all devices and platforms. If ads behave differently across devices:

1. Ensure consistent header forwarding across all CDN behaviors.
   + Verify that User-Agent, X-Forwarded-For, and custom targeting headers are forwarded consistently
   + Check that header forwarding rules apply to all relevant cache behaviors

1. Verify player compatibility with your CDN configuration.
   + Test with multiple player types (HLS.js, Video.js, native players) to identify player-specific issues
   + Check for player-specific header requirements or URL handling differences

1. Test with multiple device types to identify device-specific issues.
   + Include mobile devices, tablets, smart TVs, and desktop browsers in your testing
   + Test different operating systems and browser versions
   + Verify that device-specific ad targeting works correctly

If you've followed these troubleshooting steps and still need assistance, see [Get CDN integration support](cdn-get-help.md).

## Troubleshooting preparation


Set up tools and processes to simplify troubleshooting when CDN integration issues arise. Proactive preparation makes troubleshooting faster and more effective when issues occur.

### Enable comprehensive logging


Detailed logs are essential for diagnosing CDN integration issues. Configure logging to capture the information you'll need during troubleshooting.

1. Enable detailed CDN access logs:
   + Configure logging for all cache behaviors that handle MediaTailor requests
   + Include query strings and custom headers in log entries
   + Set up log analysis tools to identify patterns and anomalies
   + Enable real-time logs for immediate issue detection during live events
   + Configure log retention policies to maintain historical troubleshooting data

1. Configure MediaTailor logging:
   + Enable access logs for your MediaTailor configurations
   + Set up CloudWatch log groups for centralized log management
   + Configure log filters to identify error patterns

1. Set up origin server logging:
   + Enable detailed access logs on your content origin servers
   + Include request headers and response codes in logs
   + Monitor origin server performance metrics

### Add diagnostic request headers


Custom headers help track requests through your CDN and identify routing issues.

1. Configure CDN diagnostic headers:
   + Add a unique identifier to each request (for example, `X-Request-ID`)
   + Include CDN-specific information in request headers
   + Add edge location or POP (point of presence) information to track geographic routing
   + Include cache status headers (Hit, Miss, RefreshHit) for cache behavior analysis

1. Add response headers for debugging:
   + Include server identification headers
   + Add timing information for performance analysis
   + Include cache control headers for manifest requests

### Establish baseline performance metrics


Document normal performance ranges to quickly identify anomalies during troubleshooting:

1. **Record baseline metrics**:
   + Cache hit ratios for different content types
   + Response time percentiles (P50, P95, P99)
   + Error rates by status code
   + Request volume patterns by time of day

1. **Document performance expectations**:
   + Target cache hit ratios (95%\$1 for content, 90%\$1 for ads)
   + Acceptable response times (<100ms cached, <500ms origin)
   + Maximum acceptable error rates (<1% for 4xx, <0.1% for 5xx)

1. **Create performance dashboards**: Set up monitoring dashboards that show current metrics compared to baseline values.

### Prepare troubleshooting tools


Set up tools and access permissions needed for effective troubleshooting:

1. **Command-line tools**:
   + `curl` for testing HTTP requests and responses
   + `dig` or `nslookup` for DNS troubleshooting
   + HLS/DASH validation tools for manifest verification
   + Log analysis tools (grep, awk, or specialized log analyzers)

1. **Access permissions**:
   + CDN management console access for configuration review
   + MediaTailor console access for configuration verification
   + CloudWatch access for metrics and log analysis
   + Origin server access for backend troubleshooting

1. **Documentation**:
   + Network architecture diagrams
   + CDN and MediaTailor configuration documentation
   + Contact information for escalation procedures
   + Troubleshooting runbooks for common scenarios

## Workflow-specific troubleshooting guides


This universal troubleshooting guide covers common issues across all MediaTailor CDN integrations. For issues specific to particular workflows or services, consult these specialized troubleshooting resources:

Server-side ad insertion (SSAI) troubleshooting  
For SSAI-specific issues including ad insertion failures, ad transition problems, and personalization issues, see workflow-specific SSAI troubleshooting documentation.  
**Common SSAI-specific issues**:  
+ Ad insertion failures and empty ad breaks
+ Ad transition timing and synchronization problems
+ Personalization and targeting issues
+ Ad tracking and analytics discrepancies

Channel assembly troubleshooting  
For channel assembly-specific issues including manifest generation problems and time-shift functionality, see channel assembly workflow documentation.  
**Common channel assembly issues**:  
+ Manifest generation and compilation errors
+ Time-shift window and DVR functionality problems
+ Source content availability and failover issues
+ Program schedule and metadata synchronization

MediaPackage integration troubleshooting  
For MediaPackage specific issues including manifest filtering and EMP endpoint problems, see [CDN integration troubleshooting](cdn-emp-troubleshooting.md).  
**Common MediaPackage integration issues**:  
+ Manifest filtering parameter errors
+ MediaPackage endpoint connectivity issues
+ EMP-specific cache behavior problems
+ MediaPackage origin authentication issues

CloudFront specific troubleshooting  
For CloudFront specific configuration and setup issues, see CloudFront integration documentation.  
**Common CloudFront issues**:  
+ Distribution configuration and cache behavior setup
+ Origin access identity and security configuration
+ CloudFront specific error codes and responses
+ Geographic restrictions and edge location issues

**Additional resources**:
+ For performance optimization guidance, see [CDN performance optimization](cdn-optimization.md)
+ For monitoring and alerting setup, see [CDN monitoring](cdn-monitoring.md)
+ For general support and assistance, see [Get CDN integration support](cdn-get-help.md)