For developers working on streaming apps across Apple platforms, error resolution has often felt like chasing shadows. Playback interruptions might show up as vague “Operation couldn’t be completed” messages, offering little guidance for debugging or pattern recognition. When every second of viewer downtime impacts QoE and revenue, these generic error codes don’t just slow teams down, they obscure critical issues like misconfigured DRM, flaky CDNs, or malformed renditions. That’s why we’ve overhauled how the Bitmovin Player surfaces and categorizes errors on iOS, tvOS, and visionOS. With our latest SDK releases and updates to Bitmovin’s Analytics, you now get fine-grained system error visibility, both in your application logs and the Bitmovin Dashboard. This enables faster root-cause analysis, better monitoring, and smoother streaming with no guesswork required.
In this blog, we’ll walk through the specific challenges developers have faced with error reporting on Apple platforms, how the Bitmovin Player now surfaces raw system-level errors, and what improvements you’ll see in Bitmovin’s Analytics. We’ll also cover how to enable these updates and where to find updated documentation for faster, more reliable debugging, with a callout on what it means for AVPlayer users as well.
The challenge: Generic error codes that obscure root causes
Until now, debugging streaming issues on Apple platforms often meant sifting through broad, ambiguous error categories. The Bitmovin Player condensed a wide range of AVFoundation and CoreMedia errors into just a few internal error codes. That approach simplified error handling, but it came at the cost of visibility.
Teams faced three major obstacles:
- Broad buckets: Different root causes—like mis-muxed renditions, CDN delivery failures, or FairPlay certificate issues—were all grouped under the same high-level code, making pattern recognition nearly impossible.
- Dashboard blindness: In Bitmovin’s Analytics dashboard, these generic codes collapsed under a single entry in Top Errors, hiding key trends and masking repeat failures.
- Inconsistent language context: iOS error strings were reported in the viewer’s device language, creating an added layer of friction for globally distributed engineering teams.
This made it difficult to identify real trends across sessions or diagnose issues with confidence, especially at scale.
An example of dashboard blindness and how it used to look
An example of Inconsistent language context
The fix: expose the real underlying error codes
To eliminate ambiguity and give developers full visibility into playback failures, the Bitmovin Player now exposes the original system-level error codes generated by Apple’s AVFoundation and CoreMedia frameworks. These are the same low-level codes the OS generates when something goes wrong, whether it’s a network issue, a FairPlay decryption failure, or a corrupted media stream. Instead of masking them behind internal error categories, Bitmovin’s Player surfaces these codes directly through Analytics, allowing teams to pinpoint exactly what went wrong without relying on guesswork or manual log scraping.
You’ll now see a new errorCode property attached to the following event types:
- PlayerErrorEvent
- SourceErrorEvent
- AdErrorEvent
- OfflineErrorEvent
Each of these events now includes the original numeric error code from the OS, passed unmodified into Bitmovin’s Analytics. These codes power clearer, more specific error breakdowns across your logs and in the Bitmovin Analytics dashboard. Instead of vague “operation couldn’t be completed” messages, you now get actionable data tied to the actual failure. Whether you’re debugging expired FairPlay certs, CDN timeouts, or unsupported stream formats, this update helps your team isolate root causes quickly, resolve issues faster, and reduce viewer disruption at scale.
Decoding Apple system error codes
Apple’s system error codes may be detailed, but they aren’t always well-documented. Many of the codes returned by AVFoundation and CoreMedia are either poorly described or missing entirely from Apple’s public resources. So we rolled up our sleeves and catalogued over 100 distinct Apple system error codes ourselves, covering iOS, tvOS, and visionOS. Check out the developer doc for more
Bitmovin’s Analytics automatically maps recognized codes to clear, human-readable error messages. Even if your application is running an older SDK version, the backend will still resolve known system codes to their descriptions within the dashboard and API. This means you get deeper visibility and better diagnostics over time without needing to constantly upgrade your SDKs.
What you’ll see in the Dashboard
After upgrading to Bitmovin Player SDK v3.82.0 and Analytics SDK v3.10.0 or higher, you’ll start seeing detailed system error codes appear throughout Bitmovin’s Analytics dashboard. The Top Errors view surfaces each OS-level failure as its own entry, no longer grouping unrelated issues under a generic label. Errors like expired FairPlay certificates, intermittent CDN timeouts, or unsupported stream formats are now called out clearly, making it easier to spot recurring problems and take action. That level of detail carries through to individual sessions. When you drill into the Error tab on a specific playback session, you’ll find the raw system error code alongside a human-readable message from Bitmovin’s catalog. This gives your team the context it needs to resolve issues quickly and confidently.
An example of how the updated dashboard view looks
Content on Error tab in the session-level view.
Good news for AVPlayer users too
These improvements aren’t limited to Bitmovin’s Player. If you’re using Bitmovin’s Analytics alongside a native AVPlayer integration, you’ll still benefit from the enhanced error visibility. When AVPlayer surfaces raw system error codes, Bitmovin’s Analytics will automatically recognize and translate them into clear, actionable descriptions.
This means you can maintain your existing native playback implementation while still gaining access to more detailed diagnostics and a unified view of errors across all Apple platforms. Whether you’re using Bitmovin’s Player or AVPlayer directly, your analytics data will reflect the same level of clarity and granularity.
Documentation that actually helps
Alongside these product updates, we’ve overhauled our error documentation to make it easier to troubleshoot and resolve system-level issues. The new docs include clearer descriptions, an improved structure, and support for searching directly by error code. This makes it faster to identify what a specific system error means, where it originates from, and how to address it in your playback pipeline. Whether you’re responding to a production issue or reviewing logs during QA, the updated documentation is built to support real developer workflows and accelerate debugging. You can explore the full set of documented errors here:
🔗 Bitmovin Player iOS error documentation
How to get it
To take full advantage of the improved error reporting, make sure your application is running:
- Bitmovin Player SDK v3.82.0 or later for iOS, tvOS, and visionOS
- Bitmovin Analytics SDK v3.10.0 or later
Once both SDKs are in place, the errorCode property will be included automatically in relevant events, and Bitmovin’s Analytics will handle the rest. System-level error codes will start appearing throughout the dashboard with no additional configuration required.
To get started:
- Update your Podfile or Swift Package Manager references to the latest SDK versions
- Build and push your next app update
- Monitor the dashboard to confirm that detailed error codes are appearing in Top Errors and session views
These updates take just a few minutes to integrate and give your team much deeper visibility into playback issues across Apple platforms. Give it a try in your next release and let us know how it’s working for you. We’re always open to feedback and eager to keep improving the experience.
