Apple PlatformIssue Guide
#009 AVFoundation Open

AVQueuePlayer may attempt network access during offline HLS after multiple queued transitions

AvfoundationHlsPlaybackApple forumInferredIosInvestigatingPlatform behaviorReproduced
GitHub source

Inferred. This page is generated from GitHub Issue #9; GitHub remains the canonical authoring and discussion source.

Source#

Apple Developer Forums: https://developer.apple.com/forums/thread/836444

Problem#

HLS episodes are downloaded with AVAssetDownloadURLSession and played from local .movpkg assets. With AVQueuePlayer, some titles reproducibly trigger an unexpected network request after several consecutive episode transitions. If the device is offline, playback fails with NSURLErrorDomain -1009 and the next episode does not start.

Important discriminator:

start Episode 1
→ queue transitions through several episodes
→ failure at a repeatable boundary

start directly at the episode immediately before that boundary
→ no failure

Replacing the current item instead of maintaining the queue also avoids the issue, but breaks the required seamless/PiP transition behavior.

Evidence level#

Apple forum report + reproducible behavior + inferred queue/prefetch boundary.

Apple Media Engineer requested a CoreMedia (HTTP Live Streaming) logging profile and sysdiagnose to investigate. No public Apple statement currently identifies the root cause.

Key distinction#

Do not begin by assuming that -1009 means the downloaded package is incomplete.

The observable failure can be decomposed as:

local offline asset is playable
        ↓
AVQueuePlayer holds current + future items
        ↓
queue history / prewarming advances
        ↓
unexpected resource resolution occurs
        ↓
network request emitted
        ↓
offline device → -1009

Because starting directly near the failure boundary succeeds, the strongest variable is queue history / accumulated player state rather than the media bytes alone.

Investigation#

For every queued item record:

queue position
AVPlayerItem identity
asset URL actually passed to AVPlayerItem
original remote URL
local .movpkg URL
AVAssetCache.isPlayableOffline when applicable
currentItem at request time
time remaining in current item
next queued item
timestamp of insert/remove/advance

At the instant a network request appears, answer one decisive question:

Which logical player item caused the request?

Do not correlate only by wall-clock time. Correlate the requested URL against the current item, next item, and any earlier queued item.

Verification matrix#

Use the same downloaded episodes and repeat:

A. AVQueuePlayer, Episodes 1→N
B. AVQueuePlayer, start immediately before failing transition
C. AVPlayer + replaceCurrentItem(with:)
D. AVQueuePlayer with only current + next item retained
E. AVQueuePlayer with progressively deeper queue history

For each run capture:

network request URL
request timestamp
current item
queue contents
remaining playback time
AVPlayerItem.status / error
AVPlayer.error
accessLog / errorLog events
CoreMedia HLS logging

Interpretation:

A fails, B succeeds
→ queue history is a causal discriminator

A fails, C succeeds
→ issue is tied to queued lifecycle/prefetch rather than offline package alone

D succeeds while E fails as depth/history grows
→ strongly implicates accumulated queue state or prewarming

same remote URL always appears at same transition
→ inspect which item/resource inside the queue resolves that URL

Package validation#

Before blaming the queue, independently prove every downloaded asset is valid for offline playback.

Apple exposes AVAssetCache.isPlayableOffline to determine whether an asset is playable without a network connection. AVAssetDownloadURLSession is the supported API for persisting HLS assets for offline playback.

The invariant should be:

asset declared offline-playable
+
AVPlayerItem created from the local persisted asset
+
no intentionally remote dependency
=
normal playback should not require connectivity

If that invariant holds but only a long-lived AVQueuePlayer emits network traffic, the debugging boundary moves above package completeness and into player-item/queue resource resolution.

Client-side mitigation#

Until the platform cause is known:

  1. Prefer the smallest queue that still preserves required transition behavior; keep only current + next when possible.
  2. Verify every enqueued item is constructed from the local persisted asset URL, not the original remote URL.
  3. Do not treat NSURLErrorDomain -1009 as the root cause; it is the consequence of an unexpected network dependency.
  4. Preserve a deterministic reproduction starting from Episode 1 and a control starting immediately before the failing transition.
  5. Capture the CoreMedia (HTTP Live Streaming) profile and sysdiagnose with an exact failure timestamp, as requested by Apple.

Engineering rule#

For offline queue failures, distinguish asset completeness from player lifecycle/resource resolution. If the same local asset succeeds when started directly but fails only after a repeatable queue history, history is part of the state machine and must be treated as an experimental variable.

A useful investigation order is:

persisted asset identity
→ offline playability
→ AVPlayerItem source URL
→ queue topology/history
→ prefetch/resource request
→ network dependency
→ playback failure

The first divergence from the offline invariant is the root-cause boundary.

References#