diff --git a/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin.mdx b/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin.mdx index 5a6bfdbc1..b106709e4 100644 --- a/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin.mdx +++ b/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin.mdx @@ -1,7 +1,7 @@ --- title: Specify cache lifetime on a CDN resource or origin sidebarTitle: Configure CDN caching -ai-navigation: Configure CDN cache lifetime using Origin controlled or CDN controlled modes with Cache-Control headers (max-age parameter) in Apache .htaccess or Nginx nginx.conf, or set Default cache expiry in the CDN control panel to control how long files are stored in CDN servers before revalidation via ETag comparison. +ai-navigation: Configure CDN cache lifetime with origin or CDN controlled settings, advanced caching rules, video TTL guidance, and cache header checks. --- Files cannot be stored in the CDN servers' cache indefinitely. The CDN caching feature allows setting how long requested files from your origin server will be stored in the CDN server's cache. If end-users request these files, they will be loaded from the cache without additional requests to the origin server, reducing delivery time, financial spending, and the origin server load. @@ -228,5 +228,9 @@ X-Cached-Since: 2023-02-23T14:33:07+00:00 | The time when the file was cached in +## Video cache recommendations +Video files, VOD or Live, need different cache lifetimes by file type. Cache segments and single-file MP4 content longer, while keeping manifests short so players receive fresh live and playlist updates. + +For video-specific values, apply the [caching rules](/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming#step-4-configure-caching-rules) used when creating a CDN resource for video streaming. They include recommended TTLs for MP4, HLS, MPEG-DASH, live manifests, and segment files. diff --git a/cdn/cdn-resource-options/optimize-large-file-delivery.mdx b/cdn/cdn-resource-options/optimize-large-file-delivery.mdx index d4a0d7057..7586c5616 100644 --- a/cdn/cdn-resource-options/optimize-large-file-delivery.mdx +++ b/cdn/cdn-resource-options/optimize-large-file-delivery.mdx @@ -19,8 +19,35 @@ Large File Delivery Optimization can be configured in the Resource Settings and * Large File Delivery Optimization will be applied to all contents in the CDN resource, which could lead to an increased load on the origin. Therefore, consider activating [Origin Shielding](/cdn/cdn-resource-options/general/enable-and-configure-origin-shielding) before using this feature, or make any updates during off-peak hours. * Remember to [purge the resource cache](/cdn/clear-cdn-resource-cache-by-url-pattern-or-all) after enabling Large File Delivery Optimization. * Large File Delivery Optimization cannot be used in conjunction with [Fetch Compressed](/cdn/cdn-resource-options/compression/configure-fetch-compression), [Gzip Compression](/cdn/cdn-resource-options/compression/configure-gzip-and-brotli-compression#gzip), and [Brotli Compression](/cdn/cdn-resource-options/compression/configure-gzip-and-brotli-compression#brotli) within the Resource Settings or within the same rule. - - + * **HLS and MPEG-DASH don't need slicing** — those streams are already split into small segments that the CDN caches individually. + + +## Example of large file slicing + +Example of a video file which is a progressive MP4 of several GB. CDN fetches the file from origin in fixed-size chunks using HTTP Range requests, caches each chunk independently, and serves the requested byte range to the viewer. + +When a viewer requests a byte range of a large file, the CDN maps it to the 10 MB chunk(s) that contain it, fetches only those chunks from origin (through the shield), caches them, and assembles the response: + +``` +Viewer requests bytes 0–1 MB of movie.mp4 (a 2 GB file) + │ + ▼ + ┌───────────┐ needs chunk #1 (bytes 0–10 MB) → cache MISS + │ CDN edge │ + └─────┬─────┘ + │ Range: bytes=0-10485759 + ▼ + ┌───────────┐ chunk cached? no → one Range request to origin + │ Shield │ ───────────────────────────────►┌──────────┐ + └─────┬─────┘ ◄──────── 10 MB chunk #1 ───────│ Origin │ + │ caches chunk #1 └──────────┘ + ▼ + ┌───────────┐ + │ CDN edge │ caches chunk #1, returns bytes 0–1 MB to viewer + └───────────┘ + +Later: viewer seeks to bytes 1-2 MB or 2-3 MB → data is taken from the same already cached 0-10 MB chunk #1. +``` ## Configuration steps diff --git a/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming.mdx b/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming.mdx index 7a1f8e1bd..1d1060015 100644 --- a/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming.mdx +++ b/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming.mdx @@ -140,7 +140,7 @@ Optimize caching for video delivery: 2. Enable **"Always online"** with these settings: - Check **error** (serve stale cache if origin returns errors) - Check **timeout** (serve stale cache if origin times out) - - ?? **Uncheck "updating"** (important - conflicts with internal optimizations) + - **Uncheck "updating"** Why enable Always online? - Protects viewers from origin failures @@ -194,7 +194,7 @@ Optimize caching for video delivery: 2. Enable **"Always online"** with these settings: - Check **error** (serve stale cache if origin returns errors) - Check **timeout** (serve stale cache if origin times out) - - ?? **Uncheck "updating"** (important - conflicts with internal optimizations) + - **Uncheck "updating"** **Why enable Always online?** - If origin goes down, viewers can still watch cached videos diff --git a/cdn/video-cdn/improve-video-delivery-speed.mdx b/cdn/video-cdn/improve-video-delivery-speed.mdx index 1e1e5dd2b..34265fbc0 100644 --- a/cdn/video-cdn/improve-video-delivery-speed.mdx +++ b/cdn/video-cdn/improve-video-delivery-speed.mdx @@ -1,7 +1,7 @@ --- title: Improve video delivery speed for low-traffic accounts sidebarTitle: Improve delivery speed -ai-navigation: Configure Gcore CDN cache hit ratio and time-to-first-byte (TTFB) for video delivery by monitoring cache miss behavior, cache expiration, and edge server cache warming strategies for low-traffic accounts. +ai-navigation: Troubleshoot slow video delivery by checking CDN cache hits, origin 404s, live player requests, TTLs, Origin Shielding, and prefetch. --- @@ -24,6 +24,27 @@ Cache MISS: Viewer → CDN Edge → Origin Cache HIT : Viewer → CDN Edge (cache) ``` +### Example: how the cache changes over time + +To see how this works in practice, imagine three viewers watching the same video at different times: + +- **Viewer 1 — the first request.** No edge server has the video yet, so the CDN fetches it from your origin and stores a copy at the edge. This first view is a little slower while the copy is being retrieved. +- **Viewer 2 — a few minutes later.** The video is still warm in the edge cache, so it's delivered straight from the CDN — fast, with no trip back to your origin. +- **Viewer 3 — several days later.** If no one watched the video in the meantime, the edge may have already removed it to make room for more frequently requested content. The CDN then fetches it from your origin again, just like the very first time. + +This is completely normal: a cached copy stays at the edge only as long as the content is requested often enough to keep it warm. + +``` +Day 0, 10:00 Viewer 1 ─► CDN edge (empty) ─► Origin ─► copy cached at edge [MISS · slower] + +Day 0, 10:05 Viewer 2 ─► CDN edge (cached) ─► delivered to viewer [HIT · fast] + │ + │ 3–7 days pass with no requests + │ → edge evicts the video to free space + ▼ +Day 5, 14:00 Viewer 3 ─► CDN edge (empty again) ─► Origin ─► re-cached [MISS · slower] +``` + **Scenario: few viewers, rare requests (cold cache)** Edge servers do not hold files in cache indefinitely. Cached content has a limited lifetime — once it expires or is displaced by other content, it is removed. If your video library has many titles but each title is only watched occasionally, segments expire between views and must be fetched from origin again on the next request. In practice, nearly every playback session starts with a cache miss, and viewers experience the same slow start every time — regardless of how long the CDN resource has been active. @@ -59,8 +80,6 @@ You can inspect the cache status of any individual video segment directly in you If you consistently see `Cache: MISS` across multiple segments and multiple page loads, the cache is cold and the steps below will help. - - ### Check in the Gcore Customer Portal 1. Open the [CDN Statistics](https://portal.gcore.com/cdn/reports/statistics) section in the Gcore Customer Portal. @@ -70,18 +89,70 @@ If you consistently see `Cache: MISS` across multiple segments and multiple page The chart above shows two examples. The orange line stays at 100% — every viewer request is served from cache, meaning fast delivery at all times. The purple line drops repeatedly to 0% — the cache empties between bursts of traffic, so many requests go back to the origin server and viewers experience slow playback until the cache fills again. -A ratio below 80% in combination with slow delivery usually means your content is not being served from cache. For guidance on interpreting and improving the cache hit ratio, see [Cache hit ratio is low: how to solve the issue](/cdn/troubleshooting/cache-percentage-is-low-how-to-solve-the-issue). +### What cache hit ratio to expect + +The figures below are **average, typical values** — not guarantees or thresholds Gcore sets for you. Your actual ratio depends on your content, audience size, TTLs, and configuration. Use them to gauge where you stand and to decide which actions to take. **Improving the ratio is driven by your own decisions** — choosing TTLs, enabling features, and sizing your setup. Gcore provides the tools (origin shielding, cache lifetime controls, and larger shield cache for enterprise customers on a committed plan); which ones you apply is up to you. + +VOD and live streaming behave differently, so judge them against different baselines. + +**VOD (video on demand)** + +Static content should cache well, so VOD ratios are high on average. + +| Typical ratio | What it usually means | Actions you can take | +|---------------|-----------------------|----------------------| +| **90–100%** | Hot content is served from edge cache mainly | If you plan to increase traffic, consider additional optimization | +| **70–90%** | Warm content is served from cache and origin, some requests are forwarded to origin | Analyze which content is being served from origin, and if it is possible to increase TTLs and use CDN shield cache | +| **50–70%** | Cold content with the occasional appearance of frequent requests | Your content is rarely requested, or is requested from different locations across the region/world. If you're confident you have a large number of users, then connecting to a Shield will help. If you have a small number of users, then this is normal behavior for cold content. | +| **Below 50%** | A sign of low number of requests | See the section below for how to optimize hit-ratio | + +**Live streaming** + +Live runs with lower hit ratio by design: playlists and manifests (`.m3u8`, `.mpd`) carry a very short TTL and are re-requested every few seconds, so they almost always MISS. + + +Manifests will always show a low or near-zero hit ratio. That is expected and not something to fix — don't include them when assessing live cache performance. + + +So, evaluate the **segment** hit ratio only, not the overall figure. + +| Typical ratio of segments | What it usually means | Actions you can take | +|---------------|-----------------------|----------------------| +| **70–99% (segments)** | Normal for live streaming | No action needed — this is expected behavior for live. | +| **Below 70% (segments)** | Segments are being re-fetched more than expected | See the section below for how to optimize hit-ratio | ## How to improve delivery speed -### 1. Allow the cache to warm up naturally +### 1. Check what files are frequently requested from the origin + +If you see a high number of cache misses, the first step is to understand which files are being re-fetched from the origin. You can find this information in the CDN statistics and logs. + +First, check the Response statistics. If you see a large number of non-200 responses, clients may be requesting non-existent content or the origin can't find the requested content. Check why the origin can't find the content. + + +![Response statistics](/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-response-classes.png) + + +Then check what content is being requested and check the advanced analytics. + + +![Advanced analytics](/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-advanced-directories.png) + + +And if you need more detail or a breakdown down to each request, check the logs page. You can filter by status codes (200, 404, etc.) and by caching status for MISS. + + +![Logs page](/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-logs-miss.png) + + +### 2. Allow the cache to warm up naturally After a CDN resource is created or new content is uploaded, it takes time for edge servers to populate their caches as real viewers request files. In most cases, wait for steady viewer traffic before evaluating delivery performance. If your viewer traffic is consistently low (fewer than a few hundred requests per day per title), natural cache warmup may never produce a meaningfully high cache hit ratio — use the options below instead. -### 2. Pre-load popular content with Prefetch +### 3. Pre-load popular content with Prefetch If you have a set of video files that you expect to receive significant traffic, you can push them into the CDN cache before viewers request them using the Prefetch feature. This eliminates cold-start latency for those specific files. @@ -91,25 +162,23 @@ Prefetch is recommended for MP4 files. HLS and MPEG-DASH streams consist of a ma See [Load content to CDN before users request it](/cdn/load-the-content-to-cdn-before-users-request-it) for instructions. -### 3. Verify cache TTL settings +### 4. Verify cache TTL settings If your CDN resource is configured with very short or zero cache TTLs, segments are evicted quickly and the cache never stays warm. Check that your cache settings allow segments to be stored for a reasonable duration: -| File type | Recommended TTL | -|-----------|----------------| -| VOD segments (`.ts`, `.m4s`) | 1–24 hours | -| VOD playlists (`.m3u8`) | 5–60 seconds | -| Initialization segments (`.mp4`) | 1–24 hours | - TTL is the **maximum** time a file can stay in cache. In practice, content may be removed earlier — for example, when an edge server evicts less-requested files to make room for new ones, or when a cache purge is triggered. Setting a high TTL improves the chance of a cache hit but does not guarantee content will always be cached. -To review and configure cache TTLs, see [Specify cache lifetime on a CDN resource or origin](/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin). +To review and configure cache TTLs, see [Specify cache lifetime on a CDN resource for video VOD and/or Live](/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming#step-4-configure-caching-rules). + +### 5. Verify CDN resource settings -Also verify that your origin is not sending `Cache-Control: no-store`, `no-cache`, or `max-age=0` headers for video segments — these headers prevent caching entirely. See [Cache hit ratio is low: how to solve the issue](/cdn/troubleshooting/cache-percentage-is-low-how-to-solve-the-issue) for a full list of headers that block caching. +Check that the CDN resource is properly configured for video delivery. -### 4. Enable origin shielding +Apply these [recommended settings](/cdn/getting-started/create-a-cdn-resource/create-a-cdn-resource-for-video-streaming#step-4-configure-caching-rules) for better performance and delivery. + +### 6. Enable origin shielding Origin shielding is the most effective way to improve cache hit ratio for low-traffic content. It inserts a dedicated **shield (precache) server** between your origin and all CDN edge servers. @@ -123,6 +192,48 @@ To configure shielding after it is enabled on your account, see [Enable and conf **Recommended shield location**: choose the location geographically closest to your origin server. +### 7. Slice very large single-file videos + +If you deliver video as **large single MP4 files** (progressive download, not split into segments), enable [Large File Delivery Optimization](/cdn/cdn-resource-options/optimize-large-file-delivery). The CDN then fetches the file from origin in 10 MB chunks and caches each chunk independently, so viewers can start playback and seek without waiting for the whole file to be pulled. + + +This applies only to **large single-file MP4** delivery. **HLS and MPEG-DASH don't need slicing** — those formats are already split into small segments that the CDN caches individually. For how chunked origin fetching works, see [Example of large file slicing](/cdn/cdn-resource-options/optimize-large-file-delivery#example-of-large-file-slicing). + + +### 8. More help + +See [Cache hit ratio is low](/cdn/troubleshooting/cache-percentage-is-low-how-to-solve-the-issue) for more information. + +## How to improve 404 (Not Found) errors + +### 1. Check origin mapping for 404s + +When the CDN forwards a segment request to the origin and the origin returns `404 Not Found`, check origin access logs and error logs for the exact URL path shown in CDN logs. If the segment is expected to exist, fix the origin mapping before tuning cache settings. + +| Origin type | Checks | +|-------------|--------| +| S3-compatible object storage | Confirm that the object key matches the request path exactly, including bucket prefix, capitalization, file extension, and URL encoding. Check that the CDN uses the correct bucket endpoint and Host header, and that the origin has read access to the objects. | +| Web server origin, including NGINX | Confirm that `root`, `alias`, and rewrite rules map the CDN path to the real file path. Check file permissions for the web server process and confirm that `access_log` and `error_log` entries show the same `404` path. | +| Media server origin, including Wowza, Flussonic, or Nimble Streamer | Confirm that the VOD content directory, storage location, application name, and playback URL format match the requested stream. For live streams, confirm that the encoder is publishing the exact stream name and all expected renditions before the CDN requests the HLS or DASH segments. | + +For HLS and MPEG-DASH, also compare the manifest with the missing segment URL. If the manifest advertises a segment that the origin can't serve, the issue is in the packager, storage path, stream name, or file generation workflow rather than CDN caching. + +### 2. Check live players for 404s + +Live streams can generate many origin `404` responses when the player asks for a segment outside the live window. This often happens with low-latency settings, especially for MPEG-DASH, when the player calculates the live edge too aggressively and requests the nearest future segment before the origin has generated it. + +Open your player page in a browser, keep DevTools on the **Network** tab, and let playback run for several hours for long live events or 24/7 broadcasts. Filter by `404` and segment extensions (`.ts`, `.m4s`, `.mp4`) to see whether failed requests repeat over time, affect one rendition, or happen only near the live edge. + +Use the failed segment URLs to identify the pattern: + +| Pattern | Likely cause | Checks | +|---------|--------------|--------| +| The player requests segment numbers or timestamps slightly ahead of the manifest | Live delay or target latency is too low, or the player clock is ahead of the packager clock | Increase the player live delay, review low-latency mode settings, and verify DASH timing values including `suggestedPresentationDelay`, `availabilityStartTime`, and `timeShiftBufferDepth`. | +| The player requests old segments after the tab has been open for a long time | The player fell behind the sliding live window, or the browser/CDN cached an outdated manifest | Keep manifest TTL short, confirm that the player reloads the manifest, and configure the player to return to the live edge when it falls outside the live window. | +| Only one bitrate, audio track, or subtitle track returns 404 | The encoder or packager stopped producing one rendition, or the manifest references a file that was never written | Check encoder and packager logs for the affected rendition, then compare the manifest entries with files available on the origin. | + +If 404s appear only from one custom player, test the same stream in a reference player. If the reference player stays stable while the custom player keeps requesting future or expired segments, adjust the player rather than CDN cache settings. + ## Check CDN-to-origin connectivity When you see a high number of cache misses, the speed of the connection between CDN edge servers and your origin becomes critical. On every miss, the edge pulls the file directly from your origin — so if your origin is slow, distant, or under load, viewers feel that latency on every uncached request. @@ -135,6 +246,33 @@ When you see a high number of cache misses, the speed of the connection between - **[Video Streaming for VOD](/streaming/video-hosting/upload-a-video-and-embed-it-to-your-app)** — upload video files and let Gcore handle transcoding, storage, and CDN delivery as a single integrated service. - **[Video Streaming for live streams](/streaming/live-streaming/create-a-live-stream)** — ingest live streams via RTMP, SRT, or WebRTC and deliver them globally through Gcore CDN with no external origin required. +## Check response codes and origin response time + +Cache hit ratio tells you whether content is served from cache, but it won't tell you whether errors are coming from your origin. Two metrics in the Customer Portal help separate a delivery problem from an origin problem. + +Go to **Customer Portal → Reports → Statistics** and select your CDN resource: + +- **Response classes** — counts of `2xx`/`3xx`/`4xx`/`5xx` responses the CDN returned to viewers. A rise in `5xx` indicates delivery errors. Note that if your origin returns a `504`, it is counted here as a `5xx` — this view does **not** distinguish whether the error came from the origin or was generated by the CDN itself. +- **Upstream response time** — the average time, in seconds, the CDN waited for a response from your origin. A high or rising value means the origin is slow or struggling, which is a common cause of buffering and `5xx` errors during traffic peaks such as live events. + +![Check response codes and origin response time](/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-upstream-response-time.png) + +Use the values below as operational guidelines, not as an SLA. Investigate sustained values above the threshold, especially when they happen together with low cache hit ratio, rising `5xx`, or viewer buffering. + +| Request type | Expected origin response time on cache MISS | Investigate when | +|--------------|---------------------------------------------|------------------| +| Large single MP4 files or byte-range requests | Less than 1 s for TTFB; total transfer can be longer because the file is large | TTFB is above 2 s, download speed is low, or viewers wait before playback starts. Enable Large File Delivery Optimization for large single-file MP4 delivery. | +| VOD manifests (`.m3u8`, `.mpd`) from object storage or a media server | 100–500 ms | Average response time is above 500 ms, because manifests are small and should be returned quickly. | +| VOD segments (`.ts`, `.m4s`) from object storage or a media server | 200–1000 ms | Average response time is above 1 s, or segment misses show high TTFB in browser DevTools. | +| Live manifests (`.m3u8`, `.mpd`) from a media server | 100–500 ms | Average response time is above 1 s, or manifests are slow during traffic peaks. | +| Live regular segments (`.ts`, `.m4s`) from a media server | 100–500 ms | Average response time is above 1 s, or slow responses appear with `404`/`5xx` errors. | +| Low-latency live manifests and segments (`.m3u8`, `.mpd`, `.m4s`) | 500–5000+ ms | Response time can be close to the video segment duration, because in low-latency manifests and segments are produced and pulled in realtime by arrays of bytes continuously. | + + + +If `5xx` errors climb during a live event **and** upstream response time rises at the same time, the bottleneck is almost certainly your origin, not the CDN. Protect it with [origin shielding](/cdn/video-cdn/origin-shielding-for-video) and verify origin capacity. For a full origin-side checklist, see [5xx error: how to solve server issues](/cdn/troubleshooting/5xx-error-how-to-solve-server-issues). + + ## When to contact support If you have applied the steps above and delivery is still slow, contact [Support](mailto:support@gcore.com) and include: @@ -177,4 +315,7 @@ If you have applied the steps above and delivery is still slow, contact [Support Configure how long CDN edge servers keep your content cached + + Serve large single-file MP4 videos in 10 MB chunks for faster start and seek + diff --git a/cdn/video-cdn/troubleshoot-video-delivery.mdx b/cdn/video-cdn/troubleshoot-video-delivery.mdx new file mode 100644 index 000000000..494282bef --- /dev/null +++ b/cdn/video-cdn/troubleshoot-video-delivery.mdx @@ -0,0 +1,143 @@ +--- +title: Troubleshoot video delivery +sidebarTitle: Troubleshooting +ai-navigation: Diagnose and fix common video delivery problems on CDN that end viewers experience +--- + +This guide covers the video delivery problems your viewers are most likely to report. + +## First, is it the CDN or the origin? + +Before changing anything, find out where the problem is. Two quick checks usually answer this: + +- **Browser DevTools (Network tab).** Play the video, open a failing request, and look at the response: the status code (`200`, `403`, `404`, `504`…) and the `Cache` response header (`HIT` or `MISS`). See [How to check your cache hit ratio](/cdn/video-cdn/improve-video-delivery-speed#how-to-check-your-cache-hit-ratio). +- **Customer Portal → Reports → Statistics.** Select your CDN resource and compare two metrics: + - **Response classes** — counts of `2xx`/`3xx`/`4xx`/`5xx` returned to viewers. + - **Upstream response time** — the average time the CDN waited for your origin. A high or rising value points to an origin problem. + + +A reliable test for any "is it the CDN?" question: request the failing URL **directly from your origin**, bypassing the CDN. If it also fails, the problem is on the origin side. + + +## Issues your viewers may report + +### Video doesn't start, or fails only for some viewers (403 / 410) + +**What viewers see:** the video won't start or fails randomly — often for mobile users or viewers in a specific region — while it works fine for others on the same network. Player logs show `403 Forbidden` or `410 Gone`. + +**Why it happens:** these resources are protected with a [secure token](/cdn/video-cdn/secure-token). The token is tied to the viewer's IP address. On mobile networks that use CGNAT, a viewer's public IP can change between requests within the same session, so a token signed for one IP is rejected when the next request arrives from a different one. A `410` means the token has expired (its TTL elapsed, or a viewer reused an old link). + +**What to do:** + +1. Confirm the status code in DevTools or raw logs: `403` = token rejected (often an IP mismatch), `410` = token expired. +2. For CGNAT/mobile audiences, change the IP truncation prefix to `/16` with help of support team. +3. Apply correct TTL settings. +4. Verify the `expires` value is a future timestamp and that viewers aren't loading cached pages with stale URLs. + +See [Secure token for video](/cdn/video-cdn/secure-token) and [Configure and use Secure Token](/cdn/cdn-resource-options/security/use-a-secure-token/configure-and-use-secure-token) for the full token rules. Don't disable secure token to "fix" the errors — that removes your content protection. + +### Video buffers or is slow to start + +**What viewers see:** the player spins or stalls before playback, segments load slowly, and the first view of a title is always slow. + +**Why it happens:** the segment isn't in the edge cache, so the CDN fetches it from your origin on demand (a cache MISS). This is expected for content with low or uneven traffic, where segments are evicted between views. + +**What to do:** + +1. In DevTools, check the `Cache` header on segment requests. Repeated `MISS` across page loads means a cold cache. +2. Confirm your cache hit ratio in **Reports → Statistics** and compare it against the [expected benchmarks](/cdn/video-cdn/improve-video-delivery-speed#what-cache-hit-ratio-to-expect). +3. [Enable origin shielding](/cdn/video-cdn/origin-shielding-for-video) so edge misses are absorbed by a shared shield instead of your origin. +4. Verify [cache TTLs](/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin) are long enough for segments, and [prefetch](/cdn/load-the-content-to-cdn-before-users-request-it) titles you expect to be popular. + +For the full walkthrough, see [Improve video delivery speed](/cdn/video-cdn/improve-video-delivery-speed). + +### Live MPEG-DASH players get 404 for segments "from the future" + +**What viewers see:** intermittent `404 Not Found` on live MPEG-DASH segments (`.m4s`/`.mp4`), with the player stalling or rebuffering right at the live edge. The same event delivered over HLS is unaffected. + +**Why it happens:** a live DASH player works out which segment to request by combining the manifest timeline with the current wall-clock time. If the player is asking for a segment that **hasn't been generated and published to your origin yet** — because the player's clock is ahead of the packager, or the live-edge delay is too small — it requests a segment "from the future." The CDN forwards the request to origin, origin has no such segment yet, and the viewer gets a `404`. + +**What to do:** + +1. Synchronize clocks. Run NTP on your encoder/packager, and add a `` element to the MPD so players sync to a time source instead of trusting the device clock. +2. Increase the live-edge delay so players stay safely behind the newest segment: raise `suggestedPresentationDelay` (and/or `timeShiftBufferDepth`) to roughly 2–3× your segment duration. +3. Make sure your packager uploads each segment to origin **before** it announces that segment in the manifest — never advertise a segment that isn't available yet. +4. Avoid caching the `404`: use a very short negative-cache TTL (or none) so a momentary miss doesn't persist after the segment becomes available. +5. To confirm it's timing and not the CDN, request the failing segment URL directly from origin at the moment of failure — if origin also returns `404`, the segment genuinely doesn't exist yet. + +## Technical issues + +These the most common cases where monitoring systems report an issue. + +### 504 Gateway Timeout on newly uploaded or published files + +**What you see:** `504 Gateway Timeout` for videos you just uploaded or published, while older content on the same resource plays fine. + +**Why it's the origin:** the CDN opens a connection to your origin, but the origin doesn't return response headers within the timeout. This usually means the new file is still transcoding, hasn't finished propagating in storage, or the origin is slow to serve content it hasn't prepared yet. + +**What to do:** + +1. Request the failing file directly from origin (bypass the CDN). If it also times out, the issue is confirmed origin-side. +2. Compare the file's publish/upload time with the first failure. If failures cluster right after upload, let transcoding and storage propagation finish before sharing the link. +3. Make sure your origin returns the first byte well within a second; move heavy processing off the request path. +4. After publishing, [prefetch](/cdn/load-the-content-to-cdn-before-users-request-it) the file to warm the cache before viewers arrive. +5. Consider [Gcore Object Storage](/storage/use-storage-as-the-origin-for-your-cdn-resource) or [Video Streaming](/streaming/video-hosting/upload-a-video-and-embed-it-to-your-app) as your origin to remove this class of problem entirely. + +### 5xx errors during live events or traffic peaks + +**What you see:** bursts of `5xx` errors when a popular live event starts or traffic spikes, which clear up once the event ends. + +**Why it's the origin:** at peak, your origin (or an upstream CDN you pull from) can't keep up and returns `5xx`, which the CDN passes through to viewers. Origins that rate-limit by IP can also throttle the CDN's shield, producing the same symptom. + +**What to do:** + +1. In **Reports → Statistics**, line up **Response classes** (`5xx`) against **Upstream response time**. If upstream time rises with the errors, the origin is the bottleneck. +2. [Enable origin shielding](/cdn/video-cdn/origin-shielding-for-video) so thousands of concurrent edge misses collapse into a single origin request per object. +3. Provision origin capacity and bandwidth for the event ahead of time, and pre-warm popular content. +4. Remove or raise any origin rate limits that throttle CDN requests, and allowlist Gcore's servers on your origin. +5. Use short-but-cacheable TTLs for live manifests so they can be served from cache instead of hitting origin on every refresh. + +See [5xx error: how to solve server issues](/cdn/troubleshooting/5xx-error-how-to-solve-server-issues) for the full origin checklist. + +### The CDN "won't cache" your video + +**What you see:** the cache hit ratio stays low and segments are served as `MISS` even with steady, repeated traffic — so it looks like the CDN is ignoring its cache. + +**Why it's the origin:** your origin is sending response headers that tell the CDN not to cache — typically `Cache-Control: no-store`, `no-cache`, `private`, or `max-age=0`, but also `Set-Cookie` or an overly broad `Vary` header on video segments. + +**What to do:** + +1. Inspect the origin's response headers: `curl -I https:///path/to/segment.ts` and look at `Cache-Control`, `Expires`, `Pragma`, `Set-Cookie`, and `Vary`. +2. Fix the origin to send cacheable headers for video segments (a positive `max-age`, no `no-store`/`no-cache`, no per-request `Set-Cookie`). +3. If you can't change the origin, override the cache lifetime on the CDN resource so segments are cached regardless of origin headers — see [Specify cache lifetime](/cdn/cdn-resource-options/cache/specify-cache-lifetime-on-a-cdn-resource-or-origin). +4. [Purge the cache](/cdn/clear-cdn-resource-cache-by-url-pattern-or-all) and re-check the hit ratio after the change. + +For more detail, see [Cache hit ratio is low](/cdn/troubleshooting/cache-percentage-is-low-how-to-solve-the-issue). + +## When to contact support + +If you've worked through the relevant steps and delivery is still failing, contact [Support](mailto:support@gcore.com) and include: + +- The exact failing URL (the CDN segment or manifest URL, not the player page). +- The status code and `Cache` header from DevTools, and a screenshot of **Response classes** and **Upstream response time** from **Reports → Statistics**. +- Whether the content is **Live or VOD**, and **HLS or DASH**. +- The affected region, ISP, and device type (mobile, desktop, Smart TV). +- The time window (in UTC) when the problem occurred. +- The output of `https://gcore.com/.well-known/cdn-debug/json` opened from the affected viewer's network — see [When to contact support](/cdn/video-cdn/improve-video-delivery-speed#when-to-contact-support) for what this snapshot contains. + +## Related pages + + + + Diagnose buffering and a low cache hit ratio + + + Absorb edge misses and protect your origin during peaks + + + Protect HLS and DASH streams and fix 403/410 token errors + + + Look up what a specific status code means + + diff --git a/docs.json b/docs.json index 602f8ccd9..256abee4e 100644 --- a/docs.json +++ b/docs.json @@ -401,7 +401,6 @@ "group": "Video CDN", "pages": [ "cdn/video-cdn/video-cdn-overview", - "cdn/video-cdn/flv-streaming", "cdn/video-cdn/cmcd", "cdn/video-cdn/hls", "cdn/video-cdn/improve-video-delivery-speed", @@ -409,7 +408,9 @@ "cdn/video-cdn/multi-codec-vod-delivery", "cdn/video-cdn/origin-shielding-for-video", "cdn/video-cdn/secure-token", - "cdn/video-cdn/secure-token-auto-refresh" + "cdn/video-cdn/secure-token-auto-refresh", + "cdn/video-cdn/troubleshoot-video-delivery", + "cdn/video-cdn/flv-streaming" ], "expanded": false }, diff --git a/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-advanced-directories.png b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-advanced-directories.png new file mode 100644 index 000000000..16aff98f3 Binary files /dev/null and b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-advanced-directories.png differ diff --git a/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-logs-miss.png b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-logs-miss.png new file mode 100644 index 000000000..653a37c5f Binary files /dev/null and b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-logs-miss.png differ diff --git a/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-response-classes.png b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-response-classes.png new file mode 100644 index 000000000..b79bd25ed Binary files /dev/null and b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-response-classes.png differ diff --git a/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-upstream-response-time.png b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-upstream-response-time.png new file mode 100644 index 000000000..d6b3d5783 Binary files /dev/null and b/images/docs/cdn/video-cdn/improve-video-delivery-speed/cdn-stat-upstream-response-time.png differ