Troubleshoot SDK initialization errors
Solve common issues that might occur during Unity Ads SDK initialization.
Read time 1 minuteLast updated 4 days 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: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.[2] Unity Ads SDK initialization failed : Request timed out. Check your network connection and try again later.
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:This error message indicates that the SDK initialization failed due to an unknown or unexpected internal error.[52000] Unity Ads SDK initialization failed : Unknown error occurred.
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: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.[52001] Unity Ads SDK initialization failed : Invalid Game ID: $gameId. Verify the game ID in your Unity Ads Monetization dashboard.
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: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.[52002] Unity Ads SDK initialization failed : Game ID mismatch. Use the correct Game ID for your target platform from your Unity Ads Monetization dashboard.
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: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.[52003] Unity Ads SDK initialization failed : Internal protocol error occurred. Try again later.
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: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.[52004] Unity Ads SDK initialization failed : System error occurred. Try again later.
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: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.[52005] Unity Ads SDK initialization failed : Network error occurred. Try again later.
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-1022Symptoms
When you try to initialize the Unity Ads SDK, the following error message is returned: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.[52006] Unity Ads SDK initialization failed : Insufficient storage space on the device. Free up space and try again.
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)