需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

错误排查

  • iOS

更新时间不可用

了解实时消息 RTM 在不同平台上的错误排查方式，包括接入流程、关键配置和平台差异。

开启本地日志

当你的应用处于开发、测试阶段时，你可能需要 SDK 输出更详细的信息来定位并修复问题。你可以在初始化 RTM 实例的时候通过设置 AgoraRtmClientConfig 中的 AgoraRtmLogConfig 来开启日志输出并设置日志信息等级，之后即可在 IDE 中查看日志信息。

Objective-C
AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"];


AgoraRtmLogConfig* log_cfg = [[AgoraRtmLogConfig alloc] init];
log_cfg.level= AgoraRtmLogLevelError;
log_cfg.filePath= @"your_path";
log_cfg.fileSizeInKB = 512;

rtm_cfg.logConfig = log_cfg;

level 字段可以设置为 AgoraRtmLogLevelInfo、AgoraRtmLogLevelWarn、AgoraRtmLogLevelError、AgoraRtmLogLevelFatal、AgoraRtmLogLevelNone 五个等级之一，其中 AgoraRtmLogLevelInfo 输出最详细的日志信息，AgoraRtmLogLevelNone 不输出日志信息。

信息

当你的应用上线时，请将日志信息等级设置为 AgoraRtmLogLevelInfo。

错误码对照表

在调用 RTM iOS/Swift API 时，如果发生错误，SDK 会执行 completion 回调并且返回一个 AgoraRtmErrorInfo 类型的 errorInfo 返回值：

属性类型描述
errorCodeAgoraRtmErrorCode本次操作错误码。
reasonNSString本次操作出错原因。
operationNSString本次操作类型。
表格内容超出当前宽度，可横向滚动查看更多列。

其中，errorCode 和 reason 属性分别报告错误码和错误描述，你可以在下面的表格中寻找解决方法：

错误码错误描述原因及解决方法
0AgoraRtmErrorOk正确调用。
-10001AgoraRtmErrorNotInitializedSDK 未初始化。请在调用 initWithConfig 方法初始化 RTM 实例后再执行其他操作。
-10002AgoraRtmErrorNotLogin用户未登录 RTM 系统、掉线超时或者主动退出登录后调用 API。请先登录 RTM 系统。
-10003AgoraRtmErrorInvalidAppId

无效 App ID：

  • 检查 App ID 是否错误。
  • 检查 App ID 是否开通了 RTM 服务。
-10005AgoraRtmErrorInvalidToken无效 Token。检查 Token Provider 是否生成 RTM Token。
-10006AgoraRtmErrorInvalidUserId

无效用户 ID：

  • 检查用户 ID 是否为空。
  • 检查用户 ID 是否包含非法字符。
-10007AgoraRtmErrorInitServiceFailedSDK 初始化失败。请重新调用 initWithConfig 方法进行初始化。
-10008AgoraRtmErrorInvalidChannelName

无效频道名称：

  • 检查频道名是否为空。
  • 检查频道名是否包含非法字符。
-10009AgoraRtmErrorTokenExpiredToken 过期失效。你需要调用 renewToken 重新获取 Token。
-10010AgoraRtmErrorLoginNoServerResources服务器资源受限。建议重新登录。
-10011AgoraRtmErrorLoginTimeout登录超时。你需要检查当前网络是否稳定并切换到稳定网络环境中。如果你的网络处于内网环境，请检查你的防火墙是否配置了正确的域名和端口，详见防火墙白名单设置。
-10012AgoraRtmErrorLoginRejected

SDK 被服务器拒绝登录：

  • 检查 App ID 是否开通 RTM 服务。
  • 检查 Token 或 userId 是否被封禁。
-10013AgoraRtmErrorLoginAborted

由于未知问题 SDK 登录中断：

  • 检查当前网络是否稳定，切换到稳定网络环境中。
  • 当前 userId 在其他端登录。
-10014AgoraRtmErrorInvalidParameter参数无效。检查你填写的参数是否正确。
-10015AgoraRtmErrorLoginNotAuthorized没有 RTM 服务权限。检查控制台是否开通 RTM 服务。
-10016AgoraRtmErrorLoginInconsistentAppIdApp ID 不一致。检查初始化、登录、加入频道的 App ID 是否一致。
-10017AgoraRtmErrorDuplicateOperation重复操作。
-10018AgoraRtmErrorInstanceAlreadyReleased重复调用 destroy 方法释放 AgoraRtmClientKit 实例或重复调用 destroy 释放 AgoraRtmStreamChannel 实例。
-10019AgoraRtmErrorInvalidChannelType

频道类型无效。SDK 仅支持如下频道类型，请填写正确的值：

  • AgoraRtmChannelTypeMessage: Message Channel

  • AgoraRtmChannelTypeStream: Stream Channel

  • AgoraRtmChannelTypeUser: User Channel

-10020AgoraRtmErrorInvalidEncryptionParameter

消息加密参数无效。

  • 检查生成的加密密钥是否为字符串类型。
  • 检查生成的加密盐是否为字节数组类型，长度是否为 32 字节。
  • 检查加密方式与加密密钥、加密盐是否匹配。
-10021AgoraRtmErrorOperationRateExceedLimitationChannel Metadata 或 User Metadata 相关 API 的调用频率超限。请控制调用频率在 10 次/秒之内。
-10022AgoraRtmErrorServiceNotSupport服务类型不支持。请检查你在 AgoraRtmServiceType 中设置的服务类型是否正确。该错误码仅适用于私有化部署功能。
-10023AgoraRtmErrorLoginCanceled

登录操作已取消。可能原因如下：

  • 调用 loginByToken 方法后，如果你在收到调用结果之前再次调用该方法，则前一次的调用操作会被取消，SDK 会执行后一次的调用。
  • 还未成功登录就调用 logout 方法登出。
-10024AgoraRtmErrorInvalidPrivateConfig私有化部署参数设置无效。请检查你在 AgoraRtmPrivateConfig 中设置的服务类型和服务器地址是否有效。
-10025AgoraRtmErrorNotConnected未连接 RTM 服务器。在调用消息订阅、Metadata 或 Lock 模块相关 API 时，如果 RTM 服务未连接，会报这个错误。
-10026AgoraRtmErrorRenewTokenTimeout更新 Token 超时。
-11001AgoraRtmErrorChannelNotJoined

用户未加入该频道：

  • 用户不在线、已离线或未加入该频道
  • 检查 userId 是否拼写错误。
-11002AgoraRtmErrorChannelNotSubscribed

用户未订阅该频道：

  • 用户不在线、已离线或未加入该频道
  • 检查 userId 是否拼写错误。
-11003AgoraRtmErrorChannelExceedTopicUserLimitation订阅该 Topic 人数超出限制。
-11004AgoraRtmErrorChannelReused共频道模式下，RTM 释放了 Stream Channel。
-11005AgoraRtmErrorChannelInstanceExceedLimitation创建的频道数量或订阅的频道数量超出限制。详见 API 调用限制。
-11006AgoraRtmErrorChannelInErrorState频道不可用。请重新创建 Stream Channel 或重新订阅 Message Channel。
-11007AgoraRtmErrorChannelJoinFailed

加入该频道失败：

  • 检查已加入频道数量是否超限。
  • 检查频道名是否非法。
  • 检查网络是否断开连接。
-11008AgoraRtmErrorChannelInvalidTopicName

无效 Topic 名：

  • 检查 Topic 名是否包含非法字符。
  • 检查 Topic 名是否为空。
-11009AgoraRtmErrorChannelInvalidMessage无效消息。检查消息类型是否合法，RTM 只支持字符串或二进制类型消息。
-11010AgoraRtmErrorChannelMessageLengthExceedLimitation

消息长度超出限制。检查消息负载大小是否超限：

  • Message Channel 单个消息包小于 32 KB。
  • Stream Channel 单个消息包小于 1 KB。
-11011AgoraRtmErrorChannelInvalidUserList

无效用户列表：

  • 检查用户列表是否为空
  • 检查用户列表是否包含非法项。
-11012AgoraRtmErrorChannelNotAvailableStream Channel 功能未开通，当前不可用。检查控制台是否已开启 Stream Channel 功能。
-11013AgoraRtmErrorChannelTopicNotSubscribed未订阅该 Topic。
-11014AgoraRtmErrorChannelExceedTopicLimitationTopic 数量超出限制。
-11015AgoraRtmErrorChannelJoinTopicFailed加入该 Topic 失败。检查已加入 Topic 数量是否超出限制。
-11016AgoraRtmErrorChannelTopicNotJoined未加入该 Topic。未加入 Topic 就发送消息，你需要先加入 Topic。
-11017AgoraRtmErrorChannelTopicNotExist该 Topic 不存在。检查 Topic 名是否错误。
-11018AgoraRtmErrorChannelInvalidTopicMetaTopic 中的 meta 参数无效。检查 meta 参数是否超出 256 字节的限制。
-11019AgoraRtmErrorChannelSubscribeTimeout频道订阅超时。检查连接是否断开。
-11020AgoraRtmErrorChannelSubscribeTooFrequent频道订阅操作太频繁。请确保 5 秒内对同一频道的订阅操作不超过 2 次。
-11021AgoraRtmErrorChannelSubscribeFailed频道订阅失败。检查已订阅频道数量是否超出限制。
-11022AgoraRtmErrorChannelUnsubscribeFailed取消频道订阅失败。检查连接是否断开。
-11023AgoraRtmErrorChannelEncryptMessageFailed

消息加密失败：

  • 检查加密密钥是否有效。
  • 检查加密盐是否有效。
  • 检查加密方式与加密密钥、加密盐是否匹配。
-11024AgoraRtmErrorChannelPublishMessageFailed消息发布失败。检查连接是否断开。
-11026AgoraRtmErrorChannelPublishMessageTimeout消息发布超时。检查连接是否断开。
-11027AgoraRtmErrorChannelNotConnectedSDK 与 RTM 服务器断开连接。请重新登录。
-11028AgoraRtmErrorChannelLeaveFailed离开频道失败。检查连接是否断开。
-11029AgoraRtmErrorChannelCustomTypeLengthOverflowCustom type 长度溢出。customType 字段长度需要在 32 个字符以内。
-11030AgoraRtmErrorChannelInvalidCustomTypecustomType 字段无效。检查 customType 字段是否包含非法字符。
-11031AgoraRtmErrorChannelUnsupportedMessageType消息类型不支持。
-11032AgoraRtmErrorChannelPresenceNotReadyPresence 服务未就绪。请重新加入 Stream Channel 或重新订阅 Message Channel。
-11033AgoraRtmErrorChannelReceiverOffline

发送用户消息时，远端用户不在线:

  • 检查在调用方法时设置的用户 ID 是否正确。
  • 检查远端用户是否登录系统并处于在线状态。
-11034AgoraRtmErrorChannelJoinCanceled加入频道操作已取消。调用 joinWithOption 方法后，如果你在收到调用结果之前再次调用该方法，则前一次的调用操作会被取消，SDK 会执行后一次的调用。
-11035AgoraRtmErrorChannelReceiverOfflineButMessageStoreSucceeded接收端已下线，且消息成功保存至历史消息，待接收端上线后可查看消息。
-11036AgoraRtmErrorChannelReceiverOfflineAndMessageStoreFailed接收端已下线，但历史消息存储失败。
-11037AgoraRtmErrorChannelMessageDeliveredButStoreFailed消息成功发送到接收端，但历史消息存储失败。
-11040AgoraRtmErrorChannelSubscribeCanceled订阅频道操作已取消。调用 subscribe 后，如果在收到结果前调用 unsubscribe 打断订阅，会返回该错误。
-12001AgoraRtmErrorStorageOperationFailedStorage 操作失败。
-12002AgoraRtmErrorStorageMetadataItemExceedLimitationStorage Metadata Item 数量超出限制。
-12003AgoraRtmErrorStorageInvalidMetadataItem无效 Metadata Item。
-12004AgoraRtmErrorStorageInvalidArgument无效参数。
-12005AgoraRtmErrorStorageInvalidRevision无效 Revision 参数。
-12006AgoraRtmErrorStorageMetadataLengthOverflowMetadata 长度溢出。
-12007AgoraRtmErrorStorageInvalidLockName无效 Lock 名称。
-12008AgoraRtmErrorStorageLockNotAcquired未获取该 Lock。
-12009AgoraRtmErrorStorageInvalidKey无效 Metadata 键。
-12010AgoraRtmErrorStorageInvalidValue无效 Metadata 值。
-12011AgoraRtmErrorStorageKeyLengthOverflowMetadata 键长度溢出。
-12012AgoraRtmErrorStorageValueLengthOverflowMetadata 值长度溢出。
-12013AgoraRtmErrorStorageDuplicateKey重复的 Metadata Item 键。
-12014AgoraRtmErrorStorageOutdatedRevisionMetadata Item 中的 Revision 过时或 Key 不存在。
-12015AgoraRtmErrorStorageNotSubscribe未订阅该频道。
-12016AgoraRtmErrorStorageInvalidMetadataInstanceMetadata 实例不存在。请创建 Metadata 实例。
-12017AgoraRtmErrorStorageSubscribeUserExceedLimitation订阅用户 Metadata 数量超出限制。
-12018AgoraRtmErrorStorageOperationTimeoutStorage 操作超时。
-12019AgoraRtmErrorStorageNotAvailableStorage 服务不可用。
-13001AgoraRtmErrorPresenceNotConnected用户未连接到系统。
-13002AgoraRtmErrorPresenceNotWritablePresence 服务不可用。
-13003AgoraRtmErrorPresenceInvalidArgument无效参数。
-13004AgoraRtmErrorPresenceCacheTooManyStates加入频道前缓存的临时用户状态超出限制。详见 API 调用限制。
-13005AgoraRtmErrorPresenceStateCountOverflow临时用户状态键/值对数量超出限制。详见 API 调用限制。
-13006AgoraRtmErrorPresenceInvalidStateKey无效状态键。
-13007AgoraRtmErrorPresenceInvalidStateValue无效状态值。
-13008AgoraRtmErrorPresenceStateKeySizeOverflow状态键长度溢出。
-13009AgoraRtmErrorPresenceStateValueSizeOverflow状态值长度溢出
-13010AgoraRtmErrorPresenceStateDuplicateKey重复的状态键。
-13011AgoraRtmErrorPresenceUserNotExist该用户不存在。
-13012AgoraRtmErrorPresenceOperationTimeoutPresence 操作超时。
-13013AgoraRtmErrorPresenceOperationFailedPresence 操作失败。
-13014AgoraRtmErrorPresenceInactivePresence 服务未开启或当前不可用。请检查声网控制台是否已开启 Presence 服务开关；未开启时，Presence 相关 API 和依赖 Presence 的订阅选项不可用。
-13015AgoraRtmErrorPresencePendingRequestCancelledPresence 待处理请求已取消。调用 Presence 相关 API 后，如果请求完成前被取消，会返回该错误。
-13016AgoraRtmErrorPresencePendingRequestExceedLimitationPresence 待处理请求数量超过限制。请等待已有请求完成后重试。
-14001AgoraRtmErrorLockOperationFailedLock 操作失败。
-14002AgoraRtmErrorLockOperationTimeoutLock 操作超时。
-14003AgoraRtmErrorLockOperationPerformingLock 操作进行中。
-14004AgoraRtmErrorLockAlreadyExistLock 已存在。
-14005AgoraRtmErrorLockInvalidName无效 Lock 名。
-14006AgoraRtmErrorLockNotAcquired未获取该 Lock。
-14007AgoraRtmErrorLockAcquireFailed获取该 Lock 失败。
-14008AgoraRtmErrorLockNotExist该 Lock 不存在。
-14009AgoraRtmErrorLockNotAvailableLock 服务不可用。
-15001AgoraRtmErrorHistoryOperationFailed历史消息的操作失败。
-15002AgoraRtmErrorHistoryInvalidTimestamp历史消息的时间戳无效。
-15003AgoraRtmErrorHistoryOperationTimeout历史消息的操作超时。
-15004AgoraRtmErrorHistoryOperationNotPermitted没有权限进行历史消息的操作。
-15005AgoraRtmErrorHistoryNotAvailable历史消息服务不可用。
表格内容超出当前宽度，可横向滚动查看更多列。

联系我们

如果以上措施都为未能解决你的故障，或者你需要解决方案的支持，请将你的需求整理出来并通过邮箱发送到：rtm-support@agora.io。我们会在收到邮件的第一时间与你取得联系。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利