Documentation

Unity Ads Monetization

iOS API reference - Swift

iOS API reference - Objective-C

Unity Ads Monetization

Troubleshoot SDK load errors

Solve common issues that might occur while loading an ad during an ad request.
Read time 1 minuteLast updated a day ago
These errors occur when the Unity Ads SDK can't fetch ad content. If ads don't successfully load, they can't be shown, therefore the ad request won't be filled. Use this guide to quickly identify and fix issues that might occur when loading an ad.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[2] Unity Ads SDK ad load failed : Request timed out. Check your network connection and try again later.
This error message indicates that the ad load failed because the ad load request by the Unity Ads SDK to Unity's servers didn't receive a response within the expected time limit.

Causes

Common reasons for this error include:
  • Weak network connectivity (for example, weak wi-fi, or offline device)
  • Temporary network delay
  • Server response delay

Resolution

To resolve this issue, ensure your device has a reliable internet connection and try loading the ad again later.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52100] Unity Ads SDK ad load failed : No ad fill available for the requested placement.
This error message indicates that the ad load failed because the Unity Ads network was unable to complete an ad fill.

Causes

A reason for this error can be because the Unity Ads network was unable to complete an ad fill.
Note
Ad requests aren't guaranteed to be filled every time. Fill rates depend on region, campaign availability, and the advertising market price, which can fluctuate over time.

Resolution

If there's no ad fill and the ad fails to load, try reloading the ad later.If you're seeing consistently low fill rates with Unity Ads, consider setting up the app-ads.txt file (or confirming it's configured correctly). Many advertising partners will only bid on games that have correctly implemented an 
app-ads.txt
file. This standard was developed to combat fraud and increase transparency in the advertising market. You can also improve fill rates by using Unity LevelPlay or another mediation partner.For additional guidance on increasing revenue, contact your account manager or Unity Support.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52101] Unity Ads SDK ad load failed : The Unity Ads SDK is not initialized. Initialize the SDK before loading ads.
This error message indicates that the ad load failed because the SDK was not initialized before loading was attempted.

Causes

Common reasons for this error include:
  • The SDK initialization method wasn't called before loading an ad
  • The SDK initialization failed, which led to the load method never running

Resolution

To resolve this issue, ensure the Unity Ads SDK is initialized successfully before loading an ad.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52102] Unity Ads SDK ad load failed : Placement not found. Use the correct placement ID from your Unity Ads Monetization dashboard.
This error message indicates that the ad load failed because the placement ID used in your code doesn't match any placement defined for your Unity Ads project.

Causes

Common reasons for this error include:
  • Case sensitivity or spelling typo for the placement ID
  • The placement was never added in the Monetization dashboard
  • The placement exists but for the other platform (for example, loading an iOS placement while testing an Android build)
  • Using a Game ID for another app, so the placements don't correspond

Resolution

To resolve this issue, confirm the placement exists and is active in your Unity Ads Monetization dashboard, ensure you're using the correct platform-specific placement ID, and double-check spelling and case sensitivity.If you recently added a new placement, restart the app or clear the SDK cache. If you recently changed a placement ID, perform a clean rebuild to ensure the change is updated.
Note
Placements are defined per project and platform. Verify that both your Game ID and placement ID belong to the same Monetization dashboard configuration.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52103] Unity Ads SDK ad load failed : Internal protocol error occurred. Try again later.
This error message indicates that the ad load failed because the SDK encountered an unexpected or malformed response while communicating with Unity's ad servers.

Causes

Common reasons for this error include:
  • Malformed or incomplete server response
  • The SDK couldn't parse the backend's protocol
  • Backend gateway issue

Resolution

To resolve this issue, ensure a stable network connection, avoid VPNs that can modify or truncate HTTP responses, and retry loading the ad.If the error persists, capture detailed logs and share them with Unity Support for backend review.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52104] Unity Ads SDK ad load failed : The placement ID doesn't match the ad format or the placement type. Check your placement settings in the Unity Ads Monetization dashboard.
This error message indicates that the ad load failed because the specified placement ID is configured for a different ad format or placement type than the one being requested.

Causes

Common reasons for this error include:
  • Using the wrong ad format for the placement (for example, calling a method that loads interstitial ads for a rewarded placement ID)
  • Using the wrong type of placement (for example, a waterfall placement is used for bidding)
  • Setting the incorrect dashboard configuration to a different ad type than expected
  • Having a platform mismatch where the placement type may be correct but it belongs to another platform
  • Referencing a deleted or modified placement in the dashboard

Resolution

To resolve this issue, ensure in the Unity Ads Monetization dashboard that your placement's ad format matches the API call you're using, and ensure you're loading the correct platform-specific placement ID.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52105] Unity Ads SDK ad load failed : Network error occurred. Check your network connection and try again later.
This error message indicates that the ad load failed because the Unity Ads SDK couldn't establish or maintain a network connection to Unity's ad-delivery servers while trying to load an ad.

Causes

Common reasons for this error include:
  • No internet connectivity (or device is offline or in airplane mode)
  • The VPN being used is blocking Unity Ads domains
  • Device can't resolve Unity Ads endpoints

Resolution

To resolve this issue, ensure the device has a stable internet connection, disable any VPNs, and retry loading the ad after confirming network availability.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52106] Unity Ads SDK ad load failed : Insufficient storage space on the device. Free up space and try again.
This error message indicates that the ad load failed because the device ran out of available storage space, preventing the SDK from caching or writing temporary ad assets to disk.

Causes

Common reasons for this error include:
  • Your device has no free storage capacity
  • Your app's local data directory or cache is full even if your device has space

Resolution

To resolve this issue, free up storage space on the device or clear the app's cached data, then try loading the ad again.

Symptoms

When you try to load an ad using the Unity Ads SDK, the following error message is returned:
[52107] Unity Ads SDK ad load failed : Internal error occurred while parsing ad response.
This error message indicates that the ad load failed because the Unity Ads SDK encountered an internal parsing error while processing the ad response from Unity's servers.

Causes

Common reasons for this error include:
  • A malformed server response was incomplete, truncated, or incorrectly formatted
  • The SDK's parser failed while reading ad metadata
  • An outdated SDK is used against a newer protocol
  • VPNs might be blocking Unity Ads domains

Resolution

To resolve this issue, ensure a stable network connection, avoid restrictive firewalls or VPNs, and try again later to reload the ad.If the error persists, capture detailed logs and share them with Unity Support for backend review.