Documentation

Unity Ads Monetization

iOS API reference - Swift

iOS API reference - Objective-C

Unity Ads Monetization

Troubleshoot SDK initialization errors

Solve common issues that might occur during Unity Ads SDK initialization.
Read time 1 minuteLast updated a day ago
These errors occur when the Unity Ads SDK fails to initialize properly. Without successful initialization, ads can't be requested, loaded, or shown. Use this guide to quickly identify and fix issues that might occur when initializing the Unity Ads SDK.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[2] Unity Ads SDK initialization failed : Request timed out. Check your network connection and try again later.
This error message indicates that the SDK initialization failed because the network request 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)
  • Server response delay
  • Slow device

Resolution

To resolve this issue, ensure internet access and retry initialization.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52000] Unity Ads SDK initialization failed : Unknown error occurred.
This error message indicates that the SDK initialization failed due to an unknown or unexpected internal error.

Causes

A common reason for this error can be because of a temporary backend issue with Unity Ads servers.

Resolution

To resolve this issue, confirm network connectivity and Game ID correctness, and then retry initialization.If the error persists, capture detailed logs and share with Unity Support for backend review. You might need to update to the latest version of the Unity Ads SDK.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52001] Unity Ads SDK initialization failed : Invalid Game ID: $gameId. Verify the game ID in your Unity Ads Monetization dashboard.
This error message indicates that the SDK initialization failed because the Game ID provided is invalid (doesn't exist or is non-numeric) or is incorrectly referenced.

Causes

A common reason for this error is using an incorrect Game ID that can occur for one or more of the following reasons:
  • Invalid/non-numeric Game ID being used
  • Wrong Game ID copied from the dashboard or inserted into code
  • Copying a Game ID from the wrong project
  • Project being removed or archived in the Monetization dashboard

Resolution

To resolve this issue, verify the Game ID in your Monetization dashboard to ensure it matches the correct project and replace any placeholder or non-numeric values in your code.If you just created a project in the Monetization dashboard, wait a few minutes for backend sync.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52002] Unity Ads SDK initialization failed : Game ID mismatch. Use the correct Game ID for your target platform from your Unity Ads Monetization dashboard.
This error message indicates that the SDK initialization failed because the Game ID you passed doesn't match the platform the app is running on.

Causes

Common reasons for this error include:
  • Passing an iOS Game ID to an Android build
  • Passing an Android Game ID to an iOS build
  • Assigning the Game ID incorrectly or associating it with a different platform in the Monetization dashboard
  • Copying the wrong Game ID from the dashboard or inserting it into code
  • Failing to select a platform-specific Game ID at run-time, if using conditional compilation logic

Resolution

To resolve this issue, ensure you're using the correct Android or iOS Game ID from your Unity Ads dashboard, and ensure your code conditionally selects the proper one during initialization. In debug logs, confirm the SDK detects the right platform between Android and iOS.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52003] Unity Ads SDK initialization failed : Internal protocol error occurred. Try again later.
This error message indicates that the SDK initialization failed because the SDK sent a request to Unity servers and received a response that was incomplete or unexpected.

Causes

Common reasons for this error include:
  • The initialization response from Unity servers wasn't formatted correctly
  • Temporary server issue
  • Network issue

Resolution

To resolve this issue, ensure a stable connection and retry initialization later.If the error is reproducible, enable logs to capture HTTP responses and report to Unity Support for backend review.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52004] Unity Ads SDK initialization failed : System error occurred. Try again later.
This error message indicates that the SDK initialization failed because the device encountered an internal system-level issue that prevented the SDK from completing startup.

Causes

Common reasons for this error include:
  • The SDK couldn't read or write required files or system information
  • The device ran out of available storage or memory during initialization
  • The SDK encountered a read or write error when creating its local cache or folder

Resolution

To resolve this issue, ensure the app has the necessary permissions and sufficient device storage, and then try initializing again after a restart.If the error persists, clear the app's cache to remove corrupted local SDK data.

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52005] Unity Ads SDK initialization failed : Network error occurred. Try again later.
This error message indicates that the SDK initialization failed because the SDK couldn't successfully communicate with Unity servers due to a network connectivity issue.

Causes

Common reasons for this error include:
  • No internet connection (or the device is offline or in airplane mode)
  • Unstable signal or weak connection
  • VPNs may be blocking Unity Ads domains
  • The device can't resolve or reach Unity Ads endpoints

Resolution

To resolve this issue, ensure the device has a stable internet connection, avoid restrictive firewalls or VPNs, and retry initialization after verifying connectivity.If the error persists, capture logs to see if specific HTTP codes repeat (for example, 
-1009
, 
-1022
).

Symptoms

When you try to initialize the Unity Ads SDK, the following error message is returned:
[52006] Unity Ads SDK initialization failed : Insufficient storage space on the device. Free up space and try again.
This error message indicates that the SDK initialization failed because the device doesn't have enough free storage space for the Unity Ads SDK to create or write necessary local files to store configuration data, cached assets, and logs during initialization.

Causes

Common reasons for this error include:
  • Your device has zero or low available storage
  • The app's allocated cache or data directory is full
  • Persistent cache buildup (old logs, cached assets, or temporary data not cleared)

Resolution

To resolve this issue, free up device storage by clearing disk space (by deleting unused apps, media or files), clear the app's cache from device settings to remove old SDK data, if necessary, and then try to initialize the SDK again.