同步错误
概述
当使用 Atlas Device Sync 开发应用程序时，您可能会遇到错误。此部分列出了常见的同步错误，并描述了如何处理这些错误。
注意
如果您遇到此页面未列出的错误，您可以提交支持票证。
同步协议错误
下表描述了 Device Sync 协议错误以及如何处理这些错误。Atlas App Services 在 Device Sync 日志中报告错误。
错误名称 | 说明 |
|---|---|
ErrorBadClientFileIdent | 在终止并重新启用 Device Sync 后，如果服务器无法访问客户端使用的 Realm 文件，则会出现该错误。 该错误触发客户端重置。要从该错误中恢复，请执行客户端重置。 |
ErrorClientFileUserMismatch | 该错误表明，客户端尝试同步与指定用户以外的身份关联的 Realm 文件。如果在用户离线时终止并重新启用了 Device Sync，这会使他们以前的身份失效，则可能会出现该错误。 要从该错误中恢复，请删除本地 Realm 文件，然后重新打开 Realm。 |
ErrorDivergingHistories | |
ErrorPermissionDenied | 当用户的数据访问权限不足以完成特定请求时，就会出现此错误。如果用户尝试在没有读取权限的情况下打开 Realm，或在没有写入权限的情况下修改数据，就可能会发生这种情况。 要排除此错误，请查看您的规则，确保用户拥有适当的数据访问权限。 |
ErrorOtherError | 此错误表示不属于任何更具体错误的内部故障。例如，当达到免费套餐 Atlas 集群的存储限制时，就可能出现此错误。 |
Flexible Sync 错误
在应用使用 Flexible Sync 时，可能会出现以下错误。
错误名称 | 说明 | ||||
|---|---|---|---|---|---|
ErrorBadQuery | 该错误表示客户端查询无效或格式不正确。该错误包含一条信息，此消息会详细说明查询无效的原因。 要从该错误中恢复，您可能需要确认查询语法正确无误，并且使用的是服务器上支持的查询操作符。此外，确认您查询的是 Flexible Sync 配置中的可查询字段。如果您的查询使用索引可查询字段，请确保该查询满足索引可查询字段的有效客户端查询要求。 | ||||
LimitsExceeded | 此错误表明正在使用的查询已超过256 kB 的大小限制。 要从此错误中恢复，请重新构造查询，确保查询中的数据不超过可接受的大小限制。 | ||||
ErrorServerPermissionsChanged | 此错误表示身份文件的服务器权限自上次使用以来已发生改变。 该错误触发客户端重置。要从该错误中恢复，请执行客户端重置。 | ||||
ErrorInitialSyncNotCompleted | 该错误表示，客户端试图在初始同步尚未完成时打开会话。当应用刚刚启用同步，并且仍在构建同步历史记录的过程中时，可能会发生这种情况。 客户端尝试重新连接，直到此过程完成。然后，该错误得到解决，同步功能开始正常工作。 | ||||
ErrorCompensatingWrite | 当客户尝试“非法”写入时，会发生这种非致命错误。以下操作被视为非法写入：
因为本地 Realm 没有“非法”写入的概念，所以本地写入总是会成功。同步时，服务器会注意到非法写入。服务器随即撤销更改。撤销操作（称为“补偿写入”）会同步回客户端，使得客户端 Realm 不再存在非法写入。服务器也会发送该错误，让客户端知道发生了什么。 在对给定对象的非法写入和相应的补偿写入之间，对该对象的任何本地写入都会丢失。 例子请考虑以下伪代码示例： 此处，用户没有写入到 非法写入在应用日志中显示为非致命错误。非法写入可能表示应用程序代码执行您无意执行的操作。 在以下情况下，在进行“非法”写入后，您将看到 |
MongoDB 转换器错误
在 Device Sync 和 MongoDB Atlas 之间的转换过程中可能会出现以下错误。
错误名称 | 说明 |
|---|---|
MaxIntegrationAttempts | 当 MongoDB 转换器无法集成变更集时，它会重试固定次数。当转换器达到最大重试次数且无法提交更改时，会发生此错误。这通常是由集群大小不足引起的。这可能是因为事务非常大，超出了集群的可用资源。例如，设备长时间离线后，尝试同步非典型数量的批处理事务。或者，集群资源一般不足以满足应用的需求。 您可以通过升级集群层来解决此错误。 为了避免此错误，请确保关联的 MongoDB 集群满足应用的需求。此外，请确保您的应用使用最佳实践来读取和写入数据。有关更多信息，请参阅 Atlas 集群大小调整和层级选择。 |
MongoEncodingError | 当 MongoDB Atlas 写入操作（即不是同步客户端）修改文档，使其不再符合应用的模式时，就会出现此错误。与模式不匹配的文档无法同步，对此类文档锁表示的对象的任何本地更新都不会传播。 有关更多信息，请参阅未同步的文档。 |
TranslatorCorrectiveErasure | 当同步 MongoDB 集群拒绝 Device Sync 传播更改的写入操作时，就会出现此错误。这通常是由重复键异常引起的，也就是两个对象使用相同的主键。要避免此错误，请使用 ObjectId 或 UUID 作为主键值。或者，确保每个同步对象具有唯一的主键，甚至是跨分区的唯一主键。 |
TranslatorFatalError — ChangeStreamHistoryLost |
MongoDB 连接错误
如果您在新创建的集群上启用 Device Sync，该操作可能会无法解析集群 URI。出现这种情况是因为集群的 SRV 记录尚未传播。有两种可能的解决方法：
等待 5 分钟，然后启用 Atlas Device Sync。
取消链接并重新链接集群。
同步客户端错误
如果错误似乎是由连接的客户端引起的，同步协议将返回 ERROR 消息。每条消息包含错误代码号和描述。
要查看同步错误的完整列表，请参阅 错误代码列表 在 Realm Database Core GitHub 存储库中。
处理同步错误
每个使用同步的应用程序都需要一个同步错误处理程序。要了解有关同步错误处理的更多信息，请参阅您首选的 SDK：
设置客户端日志级别
您可以指定客户端日志级别。如果将日志级别设置为 trace 或 debug，则可以在应用程序开发过程中帮助诊断问题。您可以记录有关所有同步事件的一般信息或详细信息，或仅记录警告或错误。
重要
非常详细的日志记录会对性能产生负面影响。对于生产部署，请降低日志级别。
有关可用日志级别的更多信息，包括如何设置客户端日志级别，请参阅您的首选 SDK 文档。