# 排查 SDK 初始化报错

> 解决 Unity Ads SDK 初始化期间可能出现的常见问题。

当 Unity Ads SDK 无法正确初始化时，会发生这些错误。如果不成功初始化，则无法请求、加载或显示广告服务。使用此指南可以快速识别和修复初始化 Unity Ads SDK 时可能发生的问题。

**2 - Request timed out:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[2] Unity Ads SDK 初始化失败：请求超时。请检查网络连接，稍后重试。
```此报错消息表示 SDK 初始化失败，因为对 Unity 服务器的网络请求未在预期时间内收到响应。### Causes导致此报错的常见原因包括：- 网络连接薄弱（例如，wi-fi 薄弱或离线设备）
- 服务器响应延时
- 慢速设备### Resolution要解决此问题，请确保互联网访问并重试初始化。**52000 - Unknown error:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52000] Unity Ads SDK 初始化失败：发生未知报错。
```此报错消息表示由于未知或意外的内部报错，SDK 初始化失败。### Causes报错的一个常见原因可能是 Unity Ads 服务器的临时后端问题。### Resolution要解决此问题，请确认网络连接和游戏 ID 正确性，然后重试初始化。如果报错仍然存在，请捕获详细日志并与 [Unity 支持部门](https://support-ads.unity.com/s/ContactUs)共享以供后端审查。您可能需要更新到最新版本的 Unity Ads SDK。**52001 - Invalid Game ID:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52001] Unity Ads SDK 初始化失败：无效游戏 ID：$gameId。在 Unity Ads Monetization（变现）后台中验证游戏 ID。
```此报错消息表示 SDK 初始化失败，因为提供的游戏 ID 无效（不存在或非数字）或引用不正确。### Causes报错的一个常见原因是使用不正确的游戏 ID，这可能出于以下一个或多个原因：- 正在使用的无效/非数字游戏 ID
- 从后台复制或插入到代码中的游戏 ID 错误
- 从错误的项目中复制游戏 ID
- 在 Monetization（变现）后台中删除或存档的项目### Resolution要解决此问题，请在 Monetization（变现）后台中验证游戏 ID，确保其与正确的项目匹配，并替换代码中的任何占位或非数字值。如果刚在 Monetization（变现）后台中创建了项目，请等待几分钟进行后端同步。**52002 - Game ID mismatch:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52002] Unity Ads SDK 初始化失败：游戏 ID 不匹配。使用 Unity Ads Monetization（变现）后台中的目标平台的正确游戏 ID。
```此报错消息表示 SDK 初始化失败，因为您传递的游戏 ID 与 app 运行的平台不匹配。### Causes导致此报错的常见原因包括：- 将 iOS 游戏 ID 传递给 Android 构建
- 将 Android 游戏 ID 传递给 iOS 构建
- 错误分配游戏 ID 或将其与 Monetization（变现）后台中的不同平台关联
- 从后台复制错误的游戏 ID 或将其插入代码
- 如果使用条件编译逻辑，无法在运行时选择平台指定的游戏 ID### Resolution要解决此问题，请确保使用 Unity Ads Dashboard 中的正确 Android 或 iOS 游戏 ID，并确保代码在初始化期间有条件地选择正确的 ID。在调试日志中，确认 SDK 在 Android 和 iOS 之间检测到正确的平台。**52003 - Internal protocol error:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52003] Unity Ads SDK 初始化失败：发生内部协议报错。稍后重试。
```此报错消息表示 SDK 初始化失败，因为 SDK 向 Unity 服务器发送了请求，并收到了不完整或意外的响应。### Causes导致此报错的常见原因包括：- Unity 服务器的初始化响应的格式不正确
- 临时服务器问题
- 网络问题### Resolution要解决此问题，请确保连接稳定，稍后重试初始化。如果报错可重现，请启用日志以捕获 HTTP 响应并向 [Unity 支持部门](https://support-ads.unity.com/s/ContactUs)报告以供后端审查。**52004 - System error:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52004] Unity Ads SDK 初始化失败：发生系统报错。稍后重试。
```此报错消息表示 SDK 初始化失败，因为设备遇到阻止 SDK 完成启动的内部系统级别问题。### Causes导致此报错的常见原因包括：- SDK 无法读取或写入所需的文件或系统信息
- 设备在初始化期间耗尽了可用存储空间或内存
- SDK 在创建其本本地缓存或文件夹遇到读取或写入报错### Resolution要解决此问题，请确保 app 具有必要的权限和足够的设备存储空间，然后在重新启动后再次尝试初始化。如果报错仍然存在，请清除 app 的缓存以删除损坏的本地 SDK 数据。**52005 - Network error:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52005] Unity Ads SDK 初始化失败：发生网络报错。稍后重试。
```此报错消息表示 SDK 初始化失败，因为 SDK 由于网络连接问题而无法与 Unity 服务器成功通信。### Causes导致此报错的常见原因包括：- 无互联网连接（或设备离线或处于飞机模式）
- 信号不稳定或连接薄弱
- VPN 可能阻挡 Unity Ads 域
- 设备无法解析或到达 Unity Ads 终端### Resolution要解决此问题，请确保设备具有稳定的互联网连接，避免使用限制性防火墙或 VPN，并在验证连接后重试初始化。如果报错仍然存在，请捕获日志以查看指定的 HTTP 代码是否重复（例如，`-1009`、`-1022`）。**52006 - Insufficient storage space on the device:**### Symptoms尝试初始化 Unity Ads SDK 时，返回以下报错消息：```xml
[52006] Unity Ads SDK 初始化失败：设备上的存储空间不足。释放空间，然后重试。
```此报错消息表示 SDK 初始化失败，因为设备没有足够的可用存储空间让 Unity Ads SDK 在初始化期间创建或写入必要的本地文件来存储配置数据、缓存资源和日志。### Causes导致此报错的常见原因包括：- 设备的可用存储空间为零或很低
- app 分配的缓存或数据目录已满
- 持久缓存累积（旧日志、缓存资源或未清除的临时数据）### Resolution要解决此问题，请通过清除磁盘空间（通过删除未使用的应用程序、媒体或文件）来释放设备存储空间，必要时从设备设置中清除 app 的缓存以删除旧的 SDK 数据，然后尝试再次初始化 SDK。