排查 Azure 数据工厂和 Synapse 管道问题

适用于： Azure 数据工厂 Azure Synapse Analytics

本文探讨排查 Azure 数据工厂和 Synapse 管道中的外部控制活动问题的常用方法。

连接器和复制活动

如果遇到连接器问题（例如，使用复制活动时遇到错误），请参阅排查连接器问题一文。

Azure Databricks

错误代码:3200

• 消息：错误 403。

• 原因：The Databricks access token has expired.

• 建议：默认情况下，Azure Databricks 访问令牌的有效期为 90 天。 请创建新令牌并更新链接服务。

错误代码:3201

• 消息：Missing required field: settings.task.notebook_task.notebook_path.

• 原因：Bad authoring: Notebook path not specified correctly.

• 建议：在 Databricks 活动中指定笔记本路径。

• 消息：Cluster... does not exist.

• 原因：Authoring error: Databricks cluster does not exist or has been deleted.

• 建议：验证 Databricks 群集是否存在。

• 消息：Invalid Python file URI... Please visit Databricks user guide for supported URI schemes.

• 原因：Bad authoring.

• 建议：为工作区寻址方案指定绝对路径，或者为 Databricks 文件系统 (DFS) 中存储的文件指定 dbfs:/folder/subfolder/foo.py。

• 消息：{0} LinkedService should have domain and accessToken as required properties.

• 原因：Bad authoring.

• 建议：验证链接服务定义。

• 消息：{0} LinkedService should specify either existing cluster ID or new cluster information for creation.

• 原因：Bad authoring.

• 建议：验证链接服务定义。

• 消息：Node type Standard_D16S_v3 is not supported. Supported node types: Standard_DS3_v2, Standard_DS4_v2, Standard_DS5_v2, Standard_D8s_v3, Standard_D16s_v3, Standard_D32s_v3, Standard_D64s_v3, Standard_D3_v2, Standard_D8_v3, Standard_D16_v3, Standard_D32_v3, Standard_D64_v3, Standard_D12_v2, Standard_D13_v2, Standard_D14_v2, Standard_D15_v2, Standard_DS12_v2, Standard_DS13_v2, Standard_DS14_v2, Standard_DS15_v2, Standard_E8s_v3, Standard_E16s_v3, Standard_E32s_v3, Standard_E64s_v3, Standard_L4s, Standard_L8s, Standard_L16s, Standard_L32s, Standard_F4s, Standard_F8s, Standard_F16s, Standard_H16, Standard_F4s_v2, Standard_F8s_v2, Standard_F16s_v2, Standard_F32s_v2, Standard_F64s_v2, Standard_F72s_v2, Standard_NC12, Standard_NC24, Standard_NC6s_v3, Standard_NC12s_v3, Standard_NC24s_v3, Standard_L8s_v2, Standard_L16s_v2, Standard_L32s_v2, Standard_L64s_v2, Standard_L80s_v2.

• 原因：Bad authoring.

• 建议：参考错误消息。

错误代码:3202

• 消息：There were already 1000 jobs created in past 3600 seconds, exceeding rate limit: 1000 job creations per 3600 seconds.

• 原因：Too many Databricks runs in an hour.

• 建议：检查将此 Databricks 工作区用于其作业创建速率的所有管道。 如果管道总共启动的 Databricks 运行数过多，请将一些管道迁移到新工作区。

• 消息：Could not parse request object: Expected 'key' and 'value' to be set for JSON map field base_parameters, got 'key: "..."' instead.

• 原因：Authoring error: No value provided for the parameter.

• 建议：检查管道 JSON，确保 baseParameters 笔记本中的所有参数指定非空值。

• 消息：User: SimpleUserContext{userId=..., name=user@company.com, orgId=...} is not authorized to access cluster.

• 原因：不允许已生成访问令牌的用户访问链接服务中指定的 Databricks 群集。

• 建议：确保该用户在工作区中拥有所需的权限。

• 消息：Job is not fully initialized yet. Please retry later.

• 原因：作业未初始化。

• 建议：请等待并稍后重试。

错误代码:3203

• 消息：The cluster is in Terminated state, not available to receive jobs. Please fix the cluster or retry later.

• 原因：群集已终止。 对于交互式群集，此问题可能是争用条件问题。

• 建议：若要避免此错误，请使用作业群集。

错误代码:3204

• 消息：Job execution failed.

• 原因：错误消息指出了各种问题，例如意外的群集状态或特定的活动。 往往不会显示任何错误消息。

• 建议：空值

错误代码：3208

• 消息：An error occurred while sending the request.

• 原因： 与 Databricks 服务的网络连接已中断。

• 建议：如果使用的是自承载集成运行时，请确保来自集成运行时节点的网络连接是可靠的。 如果使用的是 Azure 集成运行时，则重试通常有效。

布尔运行输出开始以字符串（而不是预期的整数）形式出现

• 症状：布尔运行输出开始以字符串形式（例如，"0" 或 "1"）出现，而不是以预期的整数形式（例如，0 或 1）出现。

  

  2021 年 9 月 28 日美国东部标准时间上午 9 点左右，当依赖此输出的管道开始出现故障时，你注意到这一变化。 没有对管道进行任何更改，并且布尔输出在故障发生之前按预期到达。

  

• 原因：这个问题是由最近的一项更改引起的，这是设计使然。 更改后，如果结果是以零开头的数字，Azure 数据工厂会将该数字转换为八进制值，这是一个 bug。 此数字一直为 0 或 1，这在此更改之前从未引起过问题。 因此，为了修复八进制转换的问题，字符串输出将按原样从 Notebook 运行传递。

• 建议：将 if 条件更改为类似于 if(value=="0") 的条件。

Azure 函数

错误代码：3602

• 消息：Invalid HttpMethod: '%method;'.

• 原因： 活动有效负载中指定的 Httpmethod 不受 Azure 函数活动的支持。

• 建议：支持的 Httpmethod 为：PUT、POST、GET、DELETE、OPTIONS、HEAD 和 TRACE。

错误代码：3603

• 消息：Response Content is not a valid JObject.

• 原因： 调用的 Azure 函数未在响应中返回 JSON 有效负载。 Azure 数据工厂和 Synapse 管道 Azure 函数活动仅支持 JSON 响应内容。

• 建议：更新 Azure 函数以返回有效的 JSON 有效负载，例如，C# 函数可以返回 (ActionResult)new OkObjectResult("{\"Id\":\"123\"}");

错误代码：3606

• 消息：Azure 函数活动缺少函数密钥。

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 functionKey 的属性。

错误代码：3607

• 消息：Azure function activity missing function name.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 functionName 的属性。

错误代码：3608

• 消息：Call to provided Azure function '%FunctionName;' failed with status-'%statusCode;' and message - '%message;'.

• 原因： 活动定义中的 Azure 函数详细信息可能不正确。

• 建议：修复 Azure 函数详细信息，然后重试。

错误代码：3609

• 消息：Azure function activity missing functionAppUrl.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 functionAppUrl 的属性。

错误代码：3610

• 消息：There was an error while calling endpoint.

• 原因： 函数 URL 可能不正确。

• 建议：验证活动 JSON 中的 functionAppUrl 值是否正确，然后重试。

错误代码：3611

• 消息：Azure function activity missing Method in JSON.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 method 的属性。

错误代码：3612

• 消息：Azure function activity missing LinkedService definition in JSON.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含链接服务详细信息。

Azure 机器学习

错误代码:4101

• 消息：AzureMLExecutePipeline activity '%activityName;' has invalid value for property '%propertyName;'.

• 原因：属性 %propertyName; 的定义格式错误或缺失。

• 建议：检查是否使用正确的数据在活动 %activityName; 中定义了属性 %propertyName;。

错误代码:4110

• 消息：AzureMLExecutePipeline activity missing LinkedService definition in JSON.

• 原因：AzureMLExecutePipeline 活动定义不完整。

• 建议：检查输入的 AzureMLExecutePipeline 活动 JSON 定义是否正确包含链接服务详细信息。

错误代码:4111

• 消息：AzureMLExecutePipeline activity has wrong LinkedService type in JSON. Expected LinkedService type: '%expectedLinkedServiceType;', current LinkedService type: Expected LinkedService type: '%currentLinkedServiceType;'.

• 原因：活动定义不正确。

• 建议：检查输入的 AzureMLExecutePipeline 活动 JSON 定义是否正确包含链接服务详细信息。

错误代码:4112

• 消息：AzureMLService linked service has invalid value for property '%propertyName;'.

• 原因：属性“%propertyName;”的定义格式错误或缺失。

• 建议：检查是否使用正确的数据在链接服务中定义了属性 %propertyName;。

错误代码:4121

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：用于访问 Azure 机器学习的凭据已过期。

• 建议：验证凭据是否有效，然后重试。

错误代码:4122

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：Azure 机器学习链接服务中提供的凭据无效，或者没有操作权限。

• 建议：验证链接服务中的凭据是否有效且有权访问 Azure 机器学习。

错误代码:4123

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：活动的属性（例如 pipelineParameters）对于 Azure 机器学习 (ML) 管道无效。

• 建议：检查活动属性的值是否与链接服务中指定的已发布 Azure 机器学习管道的预期有效负载相匹配。

错误代码:4124

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：已发布的 Azure 机器学习管道终结点不存在。

• 建议：验证链接服务中指定的已发布 Azure 机器学习管道终结点是否在 Azure 机器学习中存在。

错误代码:4125

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：Azure 机器学习中出现服务器错误。

• 建议：请稍后重试。 如果问题持续出现，请联系 Azure 机器学习团队以获得帮助。

错误代码:4126

• 消息：Azure ML pipeline run failed with status: '%amlPipelineRunStatus;'. Azure ML pipeline run Id: '%amlPipelineRunId;'. Please check in Azure Machine Learning for more error logs.

• 原因：Azure 机器学习管道运行失败。

• 建议：检查 Azure 机器学习中的其他错误日志，然后修复 ML 管道。

Azure Synapse Analytics

错误代码：3250

• 消息：There are not enough resources available in the workspace, details: '%errorMessage;'

• 原因：资源不足

• 建议：尝试在工作区中结束正在运行的作业，减少请求的 vCore 数，增加工作区配额或使用其他工作区。

错误代码：3251

• 消息：There are not enough resources available in the pool, details: '%errorMessage;'

• 原因：资源不足

• 建议：尝试在池中结束正在运行的作业，减少请求的 vCore 数，扩大池的最大大小或使用其他池。

错误代码：3252

• 消息：There are not enough vcores available for your spark job, details: '%errorMessage;'

• 原因：虚拟核心不足

• 建议：尝试减少请求的 vCore 数或增加 vCore 配额。 有关详细信息，请参阅 Apache Spark 核心概念。

错误代码：3253

• 消息：There are substantial concurrent MappingDataflow executions which is causing failures due to throttling under the Integration Runtime used for ActivityId: '%activityId;'.

• 原因：达到限制阈值。

• 建议：在等待时间后重试请求。

错误代码：3254

• 消息：AzureSynapseArtifacts linked service has invalid value for property '%propertyName;'.

• 原因：属性“%propertyName;”的定义格式错误或缺失。

• 建议：检查是否使用正确的数据在链接服务中定义了“%propertyName”属性。

通用

错误代码：2103

• 消息：Please provide value for the required property '%propertyName;'.

• 原因： 尚未提供属性的必需值。

• 建议：提供消息中的值，然后重试。

错误代码：2104

• 消息：The type of the property '%propertyName;' is incorrect.

• 原因： 提供的属性类型不正确。

• 建议：修复属性的类型，然后重试。

错误代码：2105

• 消息：An invalid json is provided for property '%propertyName;'. Encountered an error while trying to parse: '%message;'.

• 原因： 属性的值无效，或未采用预期的格式。

• 建议：参阅属性的文档，并验证提供的值是否采用正确的格式和类型。

错误代码：2106

• 消息：The storage connection string is invalid. %errorMessage;

• 原因： 存储的连接字符串无效或格式不正确。

• 建议：转到 Azure 门户，找到你的存储，将连接字符串复制并粘贴到链接服务，然后重试。

错误代码：2110

• 消息：The linked service type '%linkedServiceType;' is not supported for '%executorType;' activities.

• 原因： 活动中指定了错误的链接服务。

• 建议：验证链接服务类型是否为活动支持的类型之一。 例如，对于 HDI 活动，链接服务类型可以是 HDInsight 或 HDInsightOnDemand。

错误代码：2111

• 消息：The type of the property '%propertyName;' is incorrect. The expected type is %expectedType;.

• 原因： 提供的属性的类型不正确。

• 建议：修复属性类型，然后重试。

错误代码：2112

• 消息：The cloud type is unsupported or could not be determined for storage from the EndpointSuffix '%endpointSuffix;'.

• 原因： 云类型不受支持，或者对于 EndpointSuffix 中的存储来说无法确定。

• 建议：使用另一个云中的存储，然后重试。

自定义

下表适用于 Azure Batch。

错误代码：2500

• 消息：Hit unexpected exception and execution failed.

• 原因：Can't launch command, or the program returned an error code.

• 建议：确保可执行文件存在。 如果程序已启动，请验证是否已将 stdout.txt 和 stderr.txt 上传到存储帐户。 良好的做法是在代码中包含用于调试的日志。

错误代码：2501

• 消息：Cannot access user batch account; please check batch account settings.

• 原因： Batch 访问密钥或池名称不正确。

• 建议：验证链接服务中的池名称和 Batch 访问密钥。

错误代码：2502

• 消息：Cannot access user storage account; please check storage account settings.

• 原因： 存储帐户名称或访问密钥不正确。

• 建议：验证链接服务中的存储帐户名称和访问密钥。

错误代码：2504

• 消息：Operation returned an invalid status code 'BadRequest'.

• 原因： 自定义活动的 folderPath 中的文件过多。 resourceFiles 的总大小不能超过 32,768 个字符。

• 建议：删除不必要的文件。或者压缩文件，并添加一个解压缩命令来解压缩文件。

  例如，使用 powershell.exe -nologo -noprofile -command "& { Add-Type -A 'System.IO.Compression.FileSystem'; [IO.Compression.ZipFile]::ExtractToDirectory($zipFile, $folder); }" ; $folder\yourProgram.exe

错误代码：2505

• 消息：Cannot create Shared Access Signature unless Account Key credentials are used.

• 原因： 自定义活动仅支持使用访问密钥的存储帐户。

• 建议：请参阅错误说明。

错误代码：2507

• 消息：The folder path does not exist or is empty: ...

• 原因： 存储帐户的指定路径下没有文件。

• 建议：文件夹路径必须包含要运行的可执行文件。

错误代码：2508

• 消息：There are duplicate files in the resource folder.

• 原因： folderPath 的不同子文件夹中存在多个同名的文件。

• 建议：自定义活动在 folderPath 下平展文件夹结构。 如果需要保留文件夹结构，请压缩文件，并使用一个解压缩命令将其解压缩到 Azure Batch 中。

  例如，使用 powershell.exe -nologo -noprofile -command "& { Add-Type -A 'System.IO.Compression.FileSystem'; [IO.Compression.ZipFile]::ExtractToDirectory($zipFile, $folder); }" ; $folder\yourProgram.exe

错误代码：2509

• 消息：Batch url ... is invalid; it must be in Uri format.

• 原因： Batch URL 必须类似于 https://mybatchaccount.chinaeast.batch.azure.cn

• 建议：请参阅错误说明。

错误代码：2510

• 消息：An error occurred while sending the request.

• 原因： Batch URL 无效。

• 建议：验证 Batch URL。

HDInsight

错误代码：206

• 消息：The batch ID for Spark job is invalid. Please retry your job.

• 原因： 导致此错误的服务出现了内部问题。

• 建议：此问题可能是暂时性的。 请在一段时间后重试作业。

错误代码：207

• 消息：Could not determine the region from the provided storage account. Please try using another primary storage account for the on demand HDI.

• 原因： 尝试从主存储帐户确定区域时出现内部错误。

• 建议：尝试另一个存储。

错误代码：208

• 消息：Service Principal or the MSI authenticator are not instantiated. Please consider providing a Service Principal in the HDI on demand linked service which has permissions to create an HDInsight cluster in the provided subscription and try again.

• 原因： 尝试读取服务主体或实例化 MSI 身份验证时出现内部错误。

• 建议：请考虑提供一个有权在所提供订阅中创建 HDInsight 群集的服务主体，然后重试。 验证是否正确设置了托管标识。

错误代码：2300

• 消息：Failed to submit the job '%jobId;' to the cluster '%cluster;'. Error: %errorMessage;.

• 原因： 错误消息包含类似于 The remote name could not be resolved. 的消息。 提供的群集 URI 可能无效。

• 建议：验证是否未删除该群集且提供的 URI 正确。 在浏览器中打开该 URI 时，应会看到 Ambari UI。 如果该群集位于虚拟网络中，则 URI 应是专用 URI。 若要打开该 URI，请使用同一虚拟网络中的虚拟机 (VM)。

  有关详细信息，请参阅直接连接到 Apache Hadoop 服务。

• 原因： 如果错误消息包含类似于 A task was canceled. 的消息，则意味着作业提交超时。

• 建议：这可能是普通的 HDInsight 连接问题或网络连接问题。 首先确认是否可以从任何浏览器打开 HDInsight Ambari UI。 然后检查凭据是否仍然有效。

  如果使用自承载集成运行时 (IR)，请从安装了自承载 IR 的 VM 或计算机执行此步骤。 然后再次尝试提交作业。

  有关详细信息，请阅读 Ambari Web UI。

• 原因： 如果错误消息包含类似于“User admin is locked out in Ambari”或“Unauthorized: Ambari user name or password is incorrect”的消息，则意味着 HDInsight 的凭据不正确或已过期。

• 建议：更正凭据，然后重新部署链接服务。 首先在任何浏览器中打开群集 URI 并尝试登录，以便验证凭据在 HDInsight 中是否有效。 如果凭据无效，可从 Azure 门户重置凭据。

  对于 ESP 群集，可通过自助式密码重置来重置密码。

• 原因： 如果错误消息包含类似于“502 - Web server received an invalid response while acting as a gateway or proxy server”的消息，则此错误是 HDInsight 服务返回的。

• 建议：当 Ambari 服务器进程已关闭时，往往会发生 502 错误。 可以通过重启头节点来重启 Ambari 服务。

  1. 使用 SSH 连接到 HDInsight 上的节点之一。

  2. 运行 ping headnodehost 以识别活动头节点主机。

  3. 当 Ambari 服务器位于活动头节点上时，使用 SSH 连接到活动头节点。

  4. 重启活动头节点。

     有关详细信息，请参阅 Azure HDInsight 故障排除文档。 例如：

     • Ambari UI 502 错误
     • Apache Spark Thrift 服务器的 RpcTimeoutException
     • 排查应用程序网关中的网关无效错误

• 原因： 如果错误消息包含类似于“Unable to service the submit job request as templeton service is busy with too many submit job requests”或“Queue root.joblauncher already has 500 applications, cannot accept submission of application”的消息，则意味着同时提交到 HDInsight 的作业过多。

• 建议：限制提交到 HDInsight 的并发作业数。 如果这些作业是同一活动提交的，请参阅“活动并发性”。 更改触发器，以将并发管道运行分散到不同的时间。

  请参阅 HDInsight 文档，根据错误中的建议调整 templeton.parallellism.job.submit。

错误代码：2301

• 消息：Could not get the status of the application '%physicalJobId;' from the HDInsight service. Received the following error: %message;. Please refer to HDInsight troubleshooting documentation or contact their support for further assistance.

• 原因： HDInsight 群集或服务出现问题。

• 建议：如果服务尝试请求正在运行的作业的状态时未收到 HDInsight 群集的响应，则会发生此错误。 此问题可能是群集本身造成的，也可能是 HDInsight 服务中断造成的。

  请参阅 HDInsight 故障排除文档，或联系 Azure 支持以获取更多帮助。

错误代码：2302

• 消息：Hadoop job failed with exit code '%exitCode;'. See '%logPath;/stderr' for more details. Alternatively, open the Ambari UI on the HDI cluster and find the logs for the job '%jobId;'. Contact HDInsight team for further support.

• 原因： 作业已提交到 HDI 群集，但在群集上失败。

• 建议：

1. 检查 Ambari UI：
   1. 确保所有服务仍在运行。
   2. 在 Ambari UI 中，检查仪表板中的警报部分。
      1. 有关警报的详细信息以及警报解决方法，请参阅管理和监视群集。
   3. 检查 YARN 内存。 如果 YARN 内存很高，作业处理可能会延迟。 如果没有足够的资源来适应 Spark 应用程序/作业，请纵向扩展群集，以确保群集具有足够的内存和核心。
2. 运行示例测试作业。
   1. 如果在 HDInsight 后端运行相同的作业，请检查该作业是否成功。 有关示例运行的示例，请参阅运行 HDInsight 随附的 MapReduce 示例
3. 如果作业在 HDInsight 上仍然失败，请检查要提供给支持人员的应用程序日志和信息：
   1. 检查作业是否已提交到 YARN。 如果作业尚未提交到 YARN，请使用 --master yarn。
   2. 如果应用程序已执行完毕，请收集 YARN 应用程序的开始时间和结束时间。 如果应用程序尚未执行完毕，请收集开始时间/启动时间。
   3. 使用 yarn logs -applicationId <Insert_Your_Application_ID> 检查并收集应用程序日志。
   4. 检查并收集 /var/log/hadoop-yarn/yarn 目录下的 YARN 资源管理器日志。
   5. 如果这些步骤不足以解决问题，请联系 Azure HDInsight 团队以获得支持，并提供上述日志和时间戳。

错误代码：2303

• 消息：Hadoop job failed with transient exit code '%exitCode;'. See '%logPath;/stderr' for more details. Alternatively, open the Ambari UI on the HDI cluster and find the logs for the job '%jobId;'. Try again or contact HDInsight team for further support.

• 原因： 作业已提交到 HDI 群集，但在群集上失败。

• 建议：

1. 检查 Ambari UI：
   1. 确保所有服务仍在运行。
   2. 在 Ambari UI 中，检查仪表板中的警报部分。
      1. 有关警报的详细信息以及警报解决方法，请参阅管理和监视群集。
   3. 检查 YARN 内存。 如果 YARN 内存很高，作业处理可能会延迟。 如果没有足够的资源来适应 Spark 应用程序/作业，请纵向扩展群集，以确保群集具有足够的内存和核心。
2. 运行示例测试作业。
   1. 如果在 HDInsight 后端运行相同的作业，请检查该作业是否成功。 有关示例运行的示例，请参阅运行 HDInsight 随附的 MapReduce 示例
3. 如果作业在 HDInsight 上仍然失败，请检查要提供给支持人员的应用程序日志和信息：
   1. 检查作业是否已提交到 YARN。 如果作业尚未提交到 YARN，请使用 --master yarn。
   2. 如果应用程序已执行完毕，请收集 YARN 应用程序的开始时间和结束时间。 如果应用程序尚未执行完毕，请收集开始时间/启动时间。
   3. 使用 yarn logs -applicationId <Insert_Your_Application_ID> 检查并收集应用程序日志。
   4. 检查并收集 /var/log/hadoop-yarn/yarn 目录下的 YARN 资源管理器日志。
   5. 如果这些步骤不足以解决问题，请联系 Azure HDInsight 团队以获得支持，并提供上述日志和时间戳。

错误代码：2304

• 消息：MSI authentication is not supported on storages for HDI activities.

• 原因： 为 HDInsight (HDI) 链接服务或 HDI 活动中使用的存储链接服务配置了不受支持的 MSI 身份验证。

• 建议：为 HDI 链接服务或 HDI 活动中使用的存储帐户提供完整的连接字符串。

错误代码：2305

• 消息：Failed to initialize the HDInsight client for the cluster '%cluster;'. Error: '%message;'

• 原因：HDI 群集的连接信息不正确、提供的用户无权执行所需的操作，或者 HDInsight 服务在响应来自服务的请求时出现问题。

• 建议：验证用户信息是否正确，并验证是否可以在安装 IR（如果使用自承载 IR）的 VM 上的浏览器中打开 HDI 群集的 Ambari UI，或者是否可以从任何计算机（如果使用 Azure IR）打开此 UI。

错误代码：2306

• 消息：An invalid json is provided for script action '%scriptActionName;'. Error: '%message;'

• 原因： 为脚本操作提供的 JSON 无效。

• 建议：错误消息应有助于识别问题。 请修复 JSON 配置，然后重试。

  有关详细信息，请查看 Azure HDInsight 按需链接服务。

错误代码：2310

• 消息：Failed to submit Spark job. Error: '%message;'

• 原因：服务已尝试使用 Livy API (livy/batch) 在 Spark 群集上创建批，但收到了错误。

• 建议：请按照错误消息解决问题。 如果信息不足以解决问题，请联系 HDI 团队，并向他们提供批 ID 和作业 ID - 可在服务“监视”页的活动运行输出中找到这些信息。 若要进一步进行故障排除，请收集批处理作业的完整日志。

  若要详细了解如何收集完整日志，请参阅获取批处理作业的完整日志。

错误代码：2312

• 消息：Spark job failed, batch id:%batchId;. Please follow the links in the activity run Output from the service Monitoring page to troubleshoot the run on HDInsight Spark cluster. Please contact HDInsight support team for further assistance.

• 原因： 作业在 HDInsight Spark 群集上失败。

• 建议：点击服务“监视”页上的活动运行输出中的链接，排查 HDInsight Spark 群集上的运行问题。 联系 HDInsight 支持团队以获得更多帮助。

  若要详细了解如何收集完整日志，请参阅获取批处理作业的完整日志。

错误代码：2313

• 消息：The batch with ID '%batchId;' was not found on Spark cluster. Open the Spark History UI and try to find it there. Contact HDInsight support for further assistance.

• 原因： 已在 HDInsight Spark 群集上删除该批。

• 建议：排查 HDInsight Spark 群集上的批问题。 联系 HDInsight 支持人员以获得更多帮助。

  若要详细了解如何收集完整日志，请参阅获取批处理作业的完整日志，并与 HDInsight 支持人员共享完整日志，以获得更多帮助。

错误代码：2328

• 消息：Failed to create the on demand HDI cluster. Cluster or linked service name: '%clusterName;', error: '%message;'

• 原因： 错误消息应会显示问题的详细信息。

• 建议：错误消息应有助于排查问题。

错误代码：2329

• 消息：Failed to delete the on demand HDI cluster. Cluster or linked service name: '%clusterName;', error: '%message;'

• 原因： 错误消息应会显示问题的详细信息。

• 建议：错误消息应有助于排查问题。

错误代码：2331

• 消息：The file path should not be null or empty.

• 原因： 提供的文件路径为空。

• 建议：请提供存在的文件的路径。

错误代码：2340

• 消息：HDInsightOnDemand linked service does not support execution via SelfHosted IR. Your IR name is '%IRName;'. Please select an Azure IR instead.

• 原因： HDInsightOnDemand 链接服务不支持通过 SelfHosted IR 执行。

• 建议：选择一个 Azure IR，然后重试。

错误代码：2341

• 消息：HDInsight cluster URL '%clusterUrl;' is incorrect, it must be in URI format and the scheme must be 'https'.

• 原因： 提供的 URL 未采用正确的格式。

• 建议：修复群集 URL，然后重试。

错误代码：2342

• 消息：Failed to connect to HDInsight cluster: '%errorMessage;'.

• 原因： 为群集提供了错误的凭据、存在网络配置或连接问题，或者 IR 在连接到群集时出现问题。

• 建议：

  1. 通过在浏览器中打开 HDInsight 群集的 Ambari UI，验证凭据是否正确。

  2. 如果群集位于虚拟网络 (VNet) 中，而要使用的是自承载 IR，则 HDI URL 必须是 VNet 中的专用 URL，且应在群集名称后面列出 -int。

     例如，将 https://mycluster.azurehdinsight.cn/ 更改为 https://mycluster-int.azurehdinsight.cn/。 请注意，-int 位于 mycluster 的后面，.azurehdinsight.cn 的前面

  3. 如果群集位于 VNet 中，而使用的是自承载 IR，并且已使用专用 URL，但连接仍然失败，则表示安装 IR 的 VM 在连接到 HDI 时出现了问题。

     连接到安装了 IR 的 VM，并在浏览器中打开 Ambari UI。 对群集使用专用 URL。 应该能够在浏览器中建立此连接。 如果不能，请联系 HDInsight 支持团队以获得更多帮助。

  4. 如果未使用自承载 IR，则 HDI 群集应可公开访问。 在浏览器中打开 Ambari UI，并检查它是否已打开。 如果群集或其上的服务出现任何问题，请联系 HDInsight 支持团队以获得帮助。

     链接服务中使用的 HDI 群集 URL 必须可供 IR（自承载 IR 或 Azure IR）访问，这样才能通过连接测试，并使运行正常工作。 可以通过在 VM 或任意公共计算机上的浏览器中打开该 URL，来验证此状态。

错误代码：2343

• 消息：User name and password cannot be null or empty to connect to the HDInsight cluster.

• 原因： 用户名或密码为空。

• 建议：提供连接到 HDI 所需的正确凭据，然后重试。

错误代码：2345

• 消息：Failed to read the content of the hive script. Error: '%message;'

• 原因：脚本文件不存在，或服务无法连接到脚本所在的位置。

• 建议：验证脚本是否存在，以及关联的链接服务是否有适当的连接凭据。

错误代码：2346

• 消息：Failed to create ODBC connection to the HDI cluster with error message '%message;'.

• 原因：服务已尝试与 HDI 群集建立开放式数据库连接 (ODBC) 连接，但失败并出现错误。

• 建议：

  1. 确认已正确设置 ODBC/Java Database Connectivity (JDBC) 连接。
     1. 对于 JDBC，如果使用相同的虚拟网络，则可以从以下位置获取此连接：
        Hive -> Summary -> HIVESERVER2 JDBC URL
     2. 若要确保正确设置 JDBC，请参阅在 HDInsight 中通过 JDBC 驱动程序查询 Apache Hive。
     3. 对于开放式数据库 (ODB)，请参阅教程：使用 ODBC 和 PowerShell 查询 Apache Hive 以确保设置正确。
  2. 验证 Hiveserver2、Hive 元存储和 Hiveserver2 Interactive 是否处于活动运行状态。
  3. 检查 Ambari 用户界面 (UI)：
     1. 确保所有服务仍在运行。
     2. 在 Ambari UI 中，检查仪表板中的警报部分。
        1. 有关警报的详细信息以及警报解决方法，请参阅管理和监视群集。
  4. 如果这些步骤不足以解决问题，请联系 Azure HDInsight 团队。

错误代码：2347

• 消息：Hive execution through ODBC failed with error message '%message;'.

• 原因：服务已通过 ODBC 连接将要执行的 Hive 脚本提交到 HDI 群集，但脚本在 HDI 上失败。

• 建议：

  1. 确认已正确设置 ODBC/Java Database Connectivity (JDBC) 连接。
     1. 对于 JDBC，如果使用相同的虚拟网络，则可以从以下位置获取此连接：
        Hive -> Summary -> HIVESERVER2 JDBC URL
     2. 若要确保正确设置 JDBC，请参阅在 HDInsight 中通过 JDBC 驱动程序查询 Apache Hive。
     3. 对于开放式数据库 (ODB)，请参阅教程：使用 ODBC 和 PowerShell 查询 Apache Hive 以确保设置正确。
  2. 验证 Hiveserver2、Hive 元存储和 Hiveserver2 Interactive 是否处于活动运行状态。
  3. 检查 Ambari 用户界面 (UI)：
     1. 确保所有服务仍在运行。
     2. 在 Ambari UI 中，检查仪表板中的警报部分。
        1. 有关警报的详细信息以及警报解决方法，请参阅管理和监视群集。
  4. 如果这些步骤不足以解决问题，请联系 Azure HDInsight 团队。

错误代码：2348

• 消息：The main storage has not been initialized. Please check the properties of the storage linked service in the HDI linked service.

• 原因： 未正确设置存储链接服务属性。

• 建议：HDI 活动的主存储链接服务中仅支持完整的连接字符串。 验证你是否未使用 MSI 授权或应用程序。

错误代码：2350

• 消息：Failed to prepare the files for the run '%jobId;'. HDI cluster: '%cluster;', Error: '%errorMessage;'

• 原因： 提供的凭据（用于连接到文件所在的存储）不正确，或存储中不存在文件。

• 建议：此错误是在服务对 HDI 活动进行准备时发生的。服务在将作业提交到 HDI 之前，会尝试将文件复制到主存储。 请检查提供的位置是否存在文件以及存储连接是否正确。 HDI 活动不支持与 HDI 活动相关的存储帐户中的 MSI 身份验证，因此请验证这些链接服务是否有完整的密钥或者是否使用 Azure Key Vault。

错误代码：2351

• 消息：Could not open the file '%filePath;' in container/fileSystem '%container;'.

• 原因： 文件在指定的路径不存在。

• 建议：检查该文件是否确实存在，以及连接信息指向此文件的链接服务是否有正确的凭据。

错误代码：2352

• 消息：The file storage has not been initialized. Please check the properties of the file storage linked service in the HDI activity.

• 原因： 未正确设置文件存储链接服务属性。

• 建议：验证是否已正确配置文件存储链接服务的属性。

错误代码：2353

• 消息：The script storage has not been initialized. Please check the properties of the script storage linked service in the HDI activity.

• 原因： 未正确设置脚本存储链接服务属性。

• 建议：验证是否已正确配置脚本存储链接服务的属性。

错误代码：2354

• 消息：The storage linked service type '%linkedServiceType;' is not supported for '%executorType;' activities for property '%linkedServicePropertyName;'.

• 原因： 活动不支持存储链接服务类型。

• 建议：验证所选的链接服务是否为活动支持的类型之一。 HDI 活动支持 AzureBlobStorage 和 AzureBlobFSStorage 链接服务。

错误代码：2355

• 消息：The '%value' provided for commandEnvironment is incorrect. The expected value should be an array of strings where each string has the format CmdEnvVarName=CmdEnvVarValue.

• 原因： 为 commandEnvironment 提供的值不正确。

• 建议：验证提供的值是否类似于：

  \"variableName=variableValue\"
  ]
  

  另外，验证每个变量是否仅在列表中出现一次。

错误代码：2356

• 消息：The commandEnvironment already contains a variable named '%variableName;'.

• 原因： 为 commandEnvironment 提供的值不正确。

• 建议：验证提供的值是否类似于：

  \"variableName=variableValue\"
  ]
  

  另外，验证每个变量是否仅在列表中出现一次。

错误代码：2358

• 消息：The value '%value;' for the required property 'TimeToLive' in the on demand HDInsight linked service '%linkedServiceName;' has invalid format. It should be a timespan between '00:05:00' and '24:00:00'.

• 原因： 为必需属性 TimeToLive 提供的值的格式无效。

• 建议：更新该值，使其处于建议的范围内，然后重试。

错误代码：2359

• 消息：The value '%value;' for the property 'roles' is invalid. Expected types are 'zookeeper', 'headnode', and 'workernode'.

• 原因： 为属性 roles 提供的值无效。

• 建议：将该值更新为建议的值之一，然后重试。

错误代码：2360

• 消息：The connection string in HCatalogLinkedService is invalid. Encountered an error while trying to parse: '%message;'.

• 原因： 为 HCatalogLinkedService 提供的连接字符串无效。

• 建议：将该值更新为正确的 Azure SQL 连接字符串，然后重试。

错误代码：2361

• 消息：Failed to create on demand HDI cluster. Cluster name is '%clusterName;'.

• 原因：群集创建失败，并且服务未收到 HDInsight 服务返回的错误。

• 建议：打开 Azure 门户，尝试查找具有所提供名称的 HDI 资源，然后检查预配状态。 联系 HDInsight 支持团队以获得更多帮助。

错误代码：2362

• 消息：Only Azure Blob storage accounts are supported as additional storages for HDInsight on demand linked service.

• 原因： 提供的附加存储不是 Azure Blob 存储。

• 建议：提供 Azure Blob 存储帐户作为 HDInsight 按需链接服务的附加存储。

链接服务使用 HDInsight ESP 群集时出现 SSL 错误

• 消息：Failed to connect to HDInsight cluster: 'ERROR [HY000] [Microsoft][DriverSupport] (1100) SSL certificate verification failed because the certificate is missing or incorrect.'

• 原因： 此问题很可能与系统信任存储相关。

• 解决方法：你可以导航到 Microsoft Integration Runtime\4.0\Shared\ODBC Drivers\Microsoft Hive ODBC Driver\lib 路径，并打开 DriverConfiguration64.exe 以更改设置。

  

HDI 活动在为群集做准备时停滞

如果 HDI 活动在为群集做准备时停滞，请遵循以下准则：

1. 确保超时大于下面所述的超时值，并等待执行完成或直至其超时，并在生存时间 (TTL) 其间等待，然后再提交新作业。

   启动群集所花费的最大默认时间为 2 小时，如果有任何 init 脚本，这个时间将会增加，最多再增加 2 小时。

2. 确保在同一区域中预配存储和 HDI。

3. 确保用于访问 HDI 群集的服务主体有效。

4. 如果问题仍然存在，作为解决方法，请删除 HDI 链接服务，然后使用新名称重新创建它。

Web 活动

错误代码：2001

• 消息：The length of execution output is over limit (around 4MB currently).

• 原因：执行输出大于 4 MB，但支持的最大输出响应有效负载为 4 MB。

• 建议：确保执行输出不超过 4 MB。 有关详细信息，请参阅如何横向扩展使用 Azure 数据工厂移动的数据的大小。

错误代码：2002

• 消息：The payload including configurations on activity/dataSet/linked service is too large. Please check if you have settings with very large value and try to reduce its size.

• 原因：尝试发送的有效负载太大。

• 建议：请参阅有效负载过大。

错误代码：2003

• 消息：There are substantial concurrent external activity executions which is causing failures due to throttling under subscription <subscription id>, region <region code> and limitation <current limit>. Please reduce the concurrent executions. For limits, refer https://aka.ms/adflimits.

• 原因：同时运行的活动过多。 同时触发过多管道时，可能会发生这种情况。

• 建议：减少管道并发。 可能需要分配管道的触发时间。

错误代码：2010

• 消息：The Self-hosted Integration Runtime '<SHIR name>' is offline

• 原因：自承载集成运行时脱机或 Azure 集成运行时已过期或未注册。

• 建议：确保自承载集成运行时正常运行。 有关详细信息，请参阅排查自承载集成运行时问题。

错误代码：2105

• 消息：The value type '<provided data type>', in key '<key name>' is not expected type '<expected data type>'

• 原因：动态内容表达式中生成的数据与键不匹配，导致 JSON 分析失败。

• 建议：查看关键字段并修复动态内容定义。

错误代码：2108

• 消息：Error calling the endpoint '<URL>'. Response status code: 'NA - Unknown'. More details: Exception message: 'NA - Unknown [ClientSideException] Invalid Url: <URL>. Please verify Url or integration runtime is valid and retry. Localhost URLs are allowed only with SelfHosted Integration Runtime'

• 原因：无法访问提供的 URL。 发生这种情况的原因可能是存在网络连接问题、无法分析 URL 或 Azure 集成运行时上正在使用 localhost URL。

• 建议：验证是否可以访问提供的 URL。

• 消息：Error calling the endpoint '%url;'. Response status code: '%code;'

• 原因： 某个根本性问题（例如网络连接问题、DNS 失败、服务器证书验证问题或超时）导致请求失败。

• 建议：使用 Fiddler/Postman/Netmon/Wireshark 验证请求。

  使用 Fiddler

  若要使用 Fiddler 创建受监视 Web 应用程序的 HTTP 会话，请执行以下步骤：

  1. 下载、安装并打开 Fiddler。

  2. 如果 Web 应用程序使用 HTTPS，请转到“工具”>“Fiddler 选项”>“HTTPS”。

     1. 在“HTTPS”选项卡中，选择“捕获 HTTPS 连接”和“解密 HTTPS 流量”。

        

  3. 如果应用程序使用 TLS/SSL 证书，请将 Fiddler 证书添加到设备。

     请转到：“工具”>“Fiddler 选项” > “HTTPS”>“操作”>“将根证书导出到桌面”。>

  4. 转到“文件”>“捕获流量”来关闭捕获。 或者按 F12。

  5. 清除浏览器缓存以删除所有已缓存的项；必须重新下载这些项。

  6. 创建请求：

  7. 选择“编辑器”选项卡。

     1. 设置 HTTP 方法和 URL。

     2. 根据需要添加标头和请求正文。

     3. 选择“执行”。

  8. 再次打开流量捕获，并在页面上完成出问题的事务。

  9. 请转到：“文件”>“保存”>“所有会话”。

  有关详细信息，请参阅 Fiddler 入门。

错误代码：2113

• 消息：ExtractAuthorizationCertificate: Unable to generate a certificate from a Base64 string/password combination

• 原因：无法根据 Base64 字符串/密码组合生成证书。

• 建议：验证使用的 Base64 编码 PFX 证书和密码组合是否正确。

错误代码：2403

• 消息：Get access token from MSI failed for Datafactory <DF mname>, region <region code>. Please verify resource url is valid and retry.

• 原因：无法从提供的资源 URL 获取访问令牌。

• 建议：验证是否为托管标识提供了正确的资源 URL。

常规

REST 延续令牌 NULL 错误

错误消息： {"token":null,"range":{"min":..}

原因：跨多个分区/页面查询时，后端服务返回 JObject 格式的延续令牌，具有 3 个属性：令牌、最小和最大密钥范围，例如 {"token":null,"range":{"min":"05C1E9AB0DAD76","max":"05C1E9CD673398"}})。 根据源数据，查询结果可能为 0，这表示缺少令牌，尽管要提取的数据更多。

建议：当延续令牌不为空时，如字符串 {“token”:null,“range”:{“min”:“05C1E9AB0DAD76”,“max”:“05C1E9CD673398”}}，需要使用上一个响应中的延续令牌再次调用 queryActivityRuns API。 你需要再次为查询 API 传递完整的字符串。 查询结果的后续页面中将会返回活动。 只要完整的延续令牌值不为 null，你需要继续查询，那么便可以忽略此页面中的空数组， 更多详情，请参阅 管道运行查询的 REST API。

活动停滞问题

如果观察到活动运行的时间比正常运行的时间长得多，并且几乎没有任何进展，则可能是停滞。 你可以尝试取消它，然后重试，看是否有帮助。 如果是复制活动，则可以参阅排查复制活动的性能问题一文，了解性能监视和故障排除；如果是数据流，请参阅映射数据流性能和优化指南。

有效负载太大

错误消息：The payload including configurations on activity/dataSet/linked service is too large. Please check if you have settings with very large value and try to reduce its size.

原因： 每个活动运行的有效负载包括活动配置、关联的数据集和链接服务配置（如果有），以及为每个活动类型生成的系统属性的一小部分。 如数据工厂和 Azure Synapse Analytics 的 Azure 限制文档中所述，此类有效负载大小限制为 896 KB。

建议： 达到此限制，很可能是因为从上游活动输出或外部传入了一个或多个大参数值，尤其是在控制流中跨活动传递实际数据时。 请检查是否可以减小大参数值，或调整管道逻辑以避免跨活动传递此类值，而改为在活动内处理此类值。

不受支持的压缩导致文件损坏

症状：你尝试解压缩存储在 blob 容器中的文件。 管道中的单个复制活动有一个压缩类型设置为“deflate64”（或任何不受支持的类型）的源。 此活动成功运行并生成包含在 zip 文件中的文本文件。 但是，文件中的文本有问题，该文件似乎已损坏。 当此文件在本地解压缩时，它是正常的。

原因：你的 zip 文件是通过“deflate64”算法压缩的，而 Azure 数据工厂的内部 zip 库仅支持“deflate”。 如果 zip 文件是由 Windows 系统压缩的，并且整体文件大小超过一定数量，Windows 将默认使用“deflate64”，而此算法在 Azure 数据工厂中不受支持。 另一方面，如果文件较小或你使用某些支持指定压缩算法的第三方 zip 工具，Windows 将默认使用“deflate”。

执行管道会将数组参数作为字符串传递给子管道

错误消息：Operation on target ForEach1 failed: The execution of template action 'MainForEach1' failed: the result of the evaluation of 'foreach' expression '@pipeline().parameters.<parameterName>' is of type 'String'. The result must be a valid array.

原因：即使你在“执行管道”中创建数组类型的参数（如下图所示），管道也会失败。

这是因为有效负载作为字符串从父管道传递到子管道。 当我们检查传递给子管道的输入时，我们可以看到它。

建议：要解决此问题，我们可以利用“创建数组”功能，如下图所示。

然后，我们的管道将会成功。 在输入框中我们可以看到，传递的参数是一个数组。

相关内容

尝试通过以下资源获得故障排除方面的更多帮助：

• 数据工厂 Stack Overflow 论坛