Kusto.Data 异常

2025-10-16

适用于：✅Azure 数据资源管理器

.NET SDK 中定义的所有异常都实现接口 Kusto.Cloud.Platform.Utils.ICloudPlatformException。异常在 Kusto.Cloud.Platform 程序集中定义，通过 Microsoft.Azure.Kusto.Cloud.Platform NuGet 包分发。你可以编写异常处理程序，以基于以下 get 属性检查和处理异常：

int FailureCode { get; }：返回等效的 HTTP 状态代码。
string FailureSubCode { get; }：返回等效的 HTTP 原因短语。
bool IsPermanent { get; }：返回异常的永久性。永久性异常表示调用方不应重试，因为不太可能成功，例如，因输入错误而导致的异常。

使用 Microsoft.Azure.Kusto.Data NuGet 包时从 Kusto.Data 引发的异常会继承 Kusto.Data.Exceptions.KustoException 类。所有异常都以 Kusto.Data.Exceptions 开头。

Kusto.Data 异常类别

根据根本原因，异常可能会继承以下错误类型之一：

KustoRequestException：指示请求本身或生成它的环境中的问题。此异常等效于 HTTP 状态代码 4xx，不是服务错误。有关错误列表，请参阅请求异常。
KustoServiceException：指示服务端在处理请求时出现问题。此异常等效于 HTTP 状态代码 5xx。有关错误列表，请参阅服务异常。
KustoClientException：指示向服务发送请求时出现客户端问题。具体而言，此异常通知调用方服务本身未收到请求。有关错误列表，请参阅客户端异常。

客户端异常

所有客户端异常都有失败代码 0、无失败子代码，其永久性为 False（原因列中注明的除外）。客户端异常包含以下异常类别：

异常名称	原因
`CslInvalidQueryException`	查询因自身的原因而失败。有关错误列表，请参阅客户端查询异常。
`KustoClientAuthenticationException`	客户端身份验证流失败。有关错误列表，请参阅身份验证异常。
`KustoClientInvalidConnectionStringException`	Kusto 连接字符串生成器使用了冲突的或不充分的属性进行初始化。
`KustoClientNameResolutionFailureException`	Kusto 客户端无法解析服务名称。
`KustoClientNotSupportedException`	Kusto .NET Core 客户端不支持某项功能。
`KustoClientPrincipalIdentityMustBeNullException`	要求 Kusto 客户端传输一个 PrincipalIdentity 不为 null 的 `ClientRequestProperties` 对象。
`KustoClientTemporaryStorageRetrievalException`	检索临时存储失败。
`KustoClientTimeoutAwaitingPendingOperationException`	指示等待挂起操作完成时出现超时。
`KustoClientTimeoutException`	由于客户端超时，客户端无法发送或完成请求。

客户端查询异常

所有客户端查询异常都有失败代码 0、无失败子代码，其永久性为 False（原因列中注明的除外）。

异常名称	原因
`CslBinaryOperationHasIncompatibleTypesException`	二元运算符组合了两个类型不兼容的表达式。
`CslExpectingBooleanLambdaException`	分析程序需要布尔 lambda 表达式。
`CslExpectingConstantExpressionException`	指示一个表达式失败，该表达式应表示常量。
`CslExpectingConstantNodeType`	转换查询操作已中止，因为表达式节点类型不会生成常量值。
`CslExpectingScalarExpressionException`	指示因分析程序需要标量表达式而导致的失败。
`CslExpectingScalarProjectionLambdaExpressionException`	指示当表达式应该是一个执行标量投影的 lambda 表达式时出现的失败。
`CslExpectingTableExpressionException`	指示当分析程序需要表表达式时出现的失败。
`CslExpressionHasUnsupportedNodeTypeException`	`System.Linq.Expressions.Expression` 有一个不受支持的节点类型。
`CslInternalQueryTranslationErrorException`	由于内部故障，转换查询操作已中止。
`CslNotSupportedException`	转换查询操作已中止，因为它包含不受支持的方法。
`CslUnsupportedMethodArityInExpressionException`	转换查询操作已中止，因为不支持方法参数数量。
`CslUnsupportedTypeInNewExpressionException`	转换查询操作已中止，因为不支持运算符 new 的类型参数。

身份验证异常

所有身份验证异常都有失败代码 0、无失败子代码，其永久性为 False（原因列中注明的除外）。

异常名称	原因
`KustoClientApplicationAuthenticationException`	客户端 Microsoft Entra 应用程序身份验证失败。永久性：True
`KustoClientApplicationCertificateNotFoundException`	找不到应用程序身份验证所需的证书。永久性：True
`KustoClientLocalSecretAuthenticationAccessDisabledException`	当尝试通过连接字符串来请求基于本地机密的身份验证失败且 `KustoConnectionStringBuilder.PreventAccessToLocalSecretsViaKeywords` 为 true 时。失败代码：400 失败子代码：LocalSecretAuthenticationAccessDisabled 永久性：True
`KustoClientUserAuthenticationException`	客户端 Microsoft Entra 用户身份验证失败。永久性：True
`KustoClientUserInteractiveModeNotValidException`	客户端未能向 Microsoft Entra ID 进行身份验证。永久性：True

请求异常

所有请求异常都有失败代码 0、无失败子代码，其永久性为 False（原因列中注明的除外）。

异常名称	原因
`EntityNameIsNotValidException`	指示实体名称无效。失败代码：400 失败子代码：BadRequest_EntityNameIsNotValid 永久性：True
`ClusterSuspendedException`	由于服务处于挂起状态，因此拒绝带有 `request_execute_only_if_running` 标志的请求。失败代码：412 失败子代码：PreconditionFailed 永久性：True
`KustoBadRequestException`	Kusto 服务被发送了错误请求。有关错误列表，请参阅错误请求异常。失败代码：400 失败子代码：General_BadRequest 永久性：True
`KustoConflictException`	Kusto 服务被发送了一项请求，由于服务状态的缘故，该请求无法执行。失败代码：409 失败子代码：冲突永久性：True
`KustoFailedChangeServiceStateException`	CM 无法更改服务状态。
`KustoRequestDeniedException`	Kusto 服务发送的请求的安全权限不足，无法执行。失败代码：403 失败子代码：已禁用永久性：True
`KustoRequestPayloadTooLargeException`	有效负载太大。例如，当 Kusto 被告知要处理的数据超过单个批中允许的数据时，会出现此异常。失败代码：413 失败子代码：有效负载太大永久性：True

错误请求异常

所有错误请求异常都有失败代码 0、无失败子代码，其永久性为 False（原因列中注明的除外）。

异常名称	原因
`DatabaseNotFoundException`	找不到数据库。失败代码：400 失败子代码：BadRequest_DatabaseNotExist 永久性：True
`DuplicateMappingException`	引入属性包含错误的引入映射和引入映射引用。失败代码：400 失败子代码：BadRequest_DuplicateMapping 永久性：True
`EntityNotFoundInContainerException`	找不到实体。失败代码：400 失败子代码：General_BadRequest 永久性：True
`EntityTypeIsNotValidException`	不支持此实体类型。失败代码：400 失败子代码：General_BadRequest 永久性：True
`FormatNotSupportedException`	不支持提供的格式。失败代码：400 失败子代码：BadRequest_FormatNotSupported 永久性：True
`IngestionPropertyNotSupportedInThisContextException`	引入属性在此上下文中不受支持。失败代码：400 失败子代码：BadRequest_IngestionPropertyNotSupportedInThisContext 永久性：True
`MalformedIngestionPropertyException`	引入属性的格式不正确。失败代码：400 失败子代码：BadRequest_MalformedIngestionProperty 永久性：True
`MappingNotFoundException`	找不到映射引用。失败代码：400 失败子代码：BadRequest_MappingReferenceWasNotFound 永久性：True
`MappingNotValidException`	引入属性包含无效的引入映射或引入映射引用。失败代码：400 失败子代码：BadRequest_InvalidMapping 永久性：True
`QueryCslTreeExceedsDepthsLimitsException`	csl 树超出深度限制。失败代码：400 失败子代码：General_BadRequest 永久性：True
`RelopSemanticException`	在 relop 编译阶段发生的语义错误。失败代码：400 失败子代码：General_BadRequest 永久性：True
`SemanticException`	指示语义错误。失败代码：400 失败子代码：General_BadRequest 永久性：True
`SyntaxException`	指示语法错误。失败代码：400 失败子代码：BadRequest_SyntaxError 永久性：True
`InappropriateNullLiteralException`	null 文本不能出现在它出现的上下文中。失败代码：400 失败子代码：BadRequest_SyntaxError 永久性：True
`InvalidLiteralFormatException`	由于格式不正确，分析文本失败。失败代码：400 失败子代码：BadRequest_SyntaxError 永久性：True
`TableNotFoundException`	找不到表。失败代码：400 失败子代码：BadRequest_TableNotExist 永久性：True

服务异常

所有服务异常都有失败代码 0、无失败子代码，其永久性为 False（原因列中注明的除外）。

异常名称	原因
`KustoServicePartialQueryFailureException`	查询执行已成功启动，但在完成之前失败。
`WeakConsistencyEntityNotFoundException`	指示未能在弱一致性模式下定位实体。
`KustoDataStreamException`	在 Kusto 数据流中携带错误信息的泛型异常。
`KustoRequestThrottledException`	由于限制，请求被拒绝。失败代码：429 失败子代码：TooManyRequests 永久性：False
`KustoServicePartialQueryFailureIllFormattedDataException`	在 Kusto 数据流中携带错误信息，指示数据的格式错误。失败代码：400 失败子代码：IllFormattedData 永久性：True
`KustoServicePartialQueryFailureLimitsExceededException`	在 Kusto 数据流中携带错误信息，指示已超出限制。失败代码：400 失败子代码：LimitsExceeded 永久性：True
`KustoServicePartialQueryFailureLowMemoryConditionException`	在 Kusto 数据流中携带错误信息，指示内存不足的条件。失败代码：400 失败子代码：LowMemoryCondition 永久性：True
`KustoServiceTimeoutException`	当请求执行在服务端超时时引发。失败代码：504 失败子代码：RequestExecutionTimeout 永久性：False

通过