本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 疑難排解
<a name="troubleshooting"></a>

下列主題可協助您針對使用 HealthOmics 工作流程和資料存放區時遇到的問題進行疑難排解。

**Topics**
+ [對工作流程進行故障診斷](#error-workflows)
+ [對呼叫快取問題進行故障診斷](#workflow-cache-troubleshooting)
+ [對資料存放區進行故障診斷](#error-datastores)
+ [使用 Kiro CLI 進行故障診斷](#kiro-cli-troubleshooting)

## 對工作流程進行故障診斷
<a name="error-workflows"></a>

**Topics**
+ [如何對失敗的執行進行故障診斷？](#troubleshooting-run-fail)
+ [如何對失敗的任務進行故障診斷？](#troubleshooting-task-fail)
+ [在哪裡可以找到成功完成執行的引擎日誌？](#troubleshooting-engine-logs)
+ [如何減少工作流程的輸入參數大小？](#troubleshooting-input-file-size)
+ [為什麼我的執行未完成？](#troubleshooting-unresponsive-runs)

### 如何對失敗的執行進行故障診斷？
<a name="troubleshooting-run-fail"></a>

使用 **GetRun** API 操作來擷取失敗原因。如需詳細資訊，請參閱[執行失敗原因](workflows-run-errors.md)。

### 如何對失敗的任務進行故障診斷？
<a name="troubleshooting-task-fail"></a>

檢閱任務失敗訊息中的錯誤代碼，以了解失敗。檢閱 CloudWatch 中的任務日誌，以查看任務的詳細記錄訊息。如果您沒有收到詳細的日誌訊息，您可以修改工作流程以輸出其他日誌陳述式。如需詳細資訊，請參閱[使用 CloudWatch Logs 監控 HealthOmics](monitoring-cloudwatch-logs.md)。

### 在哪裡可以找到成功完成執行的引擎日誌？
<a name="troubleshooting-engine-logs"></a>

HealthOmics 只會針對失敗的執行發佈日誌至 CloudWatch。如果執行成功完成，HealthOmics 會將引擎日誌傳送到您的 Amazon S3 儲存貯體。如需詳細資訊，請參閱[Amazon S3 中的日誌](monitoring-cloudwatch-logs.md#s3-logs)。

### 如何減少工作流程的輸入參數大小？
<a name="troubleshooting-input-file-size"></a>

您可以為工作流程指定最多 50 KB 的輸入參數。您可以使用目錄匯入或範例工作表來維持在此大小限制內。如需詳細資訊，請參閱[管理執行參數大小](workflows-run-inputs.md#run-input-file-options)。

### 為什麼我的執行未完成？
<a name="troubleshooting-unresponsive-runs"></a>

如果您的程式碼發生問題，且程序未正確結束，您的執行可能會變得沒有回應或「卡住」。如需如何防止和捕捉無回應執行的詳細資訊，請參閱 [無回應執行的指引](workflows-run-errors.md#workflows-guidance-unresponsive-runs)。

## 對呼叫快取問題進行故障診斷
<a name="workflow-cache-troubleshooting"></a>

下列主題可協助您針對呼叫快取時遇到的問題進行疑難排解。

**Topics**
+ [為什麼我的執行不會儲存至快取？](#troubleshooting-did-run-cache)
+ [為什麼任務不使用快取項目？](#troubleshooting-did-run-cache)
+ [為什麼停用任務的呼叫快取？](#troubleshooting-task-cache-disabled)

### 為什麼我的執行不會儲存至快取？
<a name="troubleshooting-did-run-cache"></a>

1. 透過檢查 GetRun API 操作回應中的 cacheId 欄位，確認執行已設定為使用快取。使用 CLI，執行此命令：`aws omics get-run —id <run_id>`。

1. 如果執行成功，請確認 GetRun 回應中傳回的快取行為為 CACHE\$1ALWAYS。如果快取行為設定為 CACHE\$1ON\$1FAILURE，則執行只會在失敗時儲存至快取。

### 為什麼任務不使用快取項目？
<a name="troubleshooting-did-run-cache"></a>

在 `/aws/omics/WorkflowLog` CloudWatch 日誌群組中，開啟執行快取的日誌串流：**runCache/<cache\$1id>/<cache\$1uuid>**。

1. 確認先前的執行已為您預期要快取的任務建立快取項目。儲存到快取的執行會以 CACHE\$1ENTRY\$1CREATED 的日誌訊息記錄。

1. 找到任務的 CACHE\$1MISS 日誌，並執行已完成的日誌。如果沒有日誌項目，請檢查執行是否設定為使用快取。

1. 如果已建立快取項目，請確認兩個任務CPUs、記憶體、GPUs 和容器摘要都相同。建立快取項目之任務的任務 ARN 位於日誌訊息中。

1. 如果兩個任務的運算需求相符，請確認任務之間的輸入未變更。若要這樣做，請開啟引擎日誌。如果執行的狀態為 FAILED，則日誌將在 Cloudwatch Log Group /aws/omics/WorkflowLog 中。否則，您可以在執行的輸出目錄中找到引擎日誌。

### 為什麼停用任務的呼叫快取？
<a name="troubleshooting-task-cache-disabled"></a>

檢查任務是否設定為使用工作流程引擎功能選擇退出快取：
+ 對於 WDL 工作流程：檢查中繼區段`true`中的任務是否將揮發性設定為
+ 對於 Nextflow 工作流程：檢查任務是否將快取指令設定為 `false`
+ 對於 CWL 工作流程：檢查任務是否已`false`針對 WorkReuse 功能將 enableReuse 設定為 WorkReuse 

## 對資料存放區進行故障診斷
<a name="error-datastores"></a>

**Topics**
+ [為什麼我的讀取集上的 S3 GetObject 失敗？](#sequence-store-s3-getobject-failing)
+ [為什麼我在 Athena 中看不到註釋存放區或變體存放區？](#athena-troubleshooting)
+ [為什麼我無法存取 Athena 中的資料存放區？](#athena-engine-troubleshooting)

### 為什麼我的讀取集上的 S3 GetObject 失敗？
<a name="sequence-store-s3-getobject-failing"></a>

最常見的是，失敗是因為缺少許可。序列存放區 S3 讀取許可是一種雙向組態，需要序列存放區 S3 存取政策允許存取，且 IAM 主體必須連接允許存取的政策。如需政策需求的詳細資訊，請參閱 [使用 Amazon S3 URIs 存取資料的許可](s3-sharing.md)。檢查下列組態是否已就緒：
+ 序列存放區 S3 存取政策明確允許存取 IAM 主體或主體帳戶的根目錄。
+ 檢查 IAM 主體是否具有明確提供存取資源許可的政策。請注意，定義許可時，IAM 主體政策必須使用存取點 ARN，而不是存取點別名型路徑，而且 ARN 處於 條件，而不是用來指定資源。
+ 如果您的存放區使用客戶受管金鑰 (CMK-KMS)，請確定 IAM 主體對金鑰具有 kms:decrypt 許可。如需跨帳戶設定用量，請參閱 KMS [跨帳戶存取指南](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html)。

如果您有使用標籤型存取控制的政策，請確定下列事項：
+ 確定序列存放區已完成標籤同步。因此，存放區的狀態必須為 **active**，而不是 **updating**。
+ 確保讀取集和政策上的標籤索引鍵或索引鍵值中沒有錯別字。

### 為什麼我在 Athena 中看不到註釋存放區或變體存放區？
<a name="athena-troubleshooting"></a>

在 Lake Formation 中，請務必根據與您共用的存放區建立資源連結。建立您有權存取的資源連結後，應該會在 Athena 中顯示該存放區。如需詳細資訊，請參閱[設定 Lake Formation 以使用 HealthOmics](setting-up-lf.md)。

### 為什麼我無法存取 Athena 中的資料存放區？
<a name="athena-engine-troubleshooting"></a>

如果您的註釋或變體存放區可見，但您收到錯誤訊息，指出存取遭拒，請檢查您正在使用的查詢引擎版本。僅支援使用引擎版本 3 執行的查詢。若要進一步了解 Athena 查詢引擎版本，請參閱 [Amazon Athena 文件](https://docs.aws.amazon.com/athena/latest/ug/engine-versions-changing.html)。

## 使用 Kiro CLI 進行故障診斷
<a name="kiro-cli-troubleshooting"></a>

[Kiro CLI](https://docs.aws.amazon.com/kiro/latest/userguide/what-is.html) 可以透過下列方式協助您簡化故障診斷程序：
+ 分析工作流程執行和偵錯任務失敗
+ 收集相關日誌和錯誤訊息
+ 建立連接所有必要偵錯日誌的 AWS 支援案例
+ 從提交至 AWS Support 的資訊中修訂個人身分識別資訊 (PII)

如需搭配 使用 Kiro CLI AWS HealthOmics 進行疑難排解和建立支援案例的詳細資訊，請參閱 GitHub 上的 [HealthOmics Agentic 生成式 AI 教學](https://github.com/aws-samples/aws-healthomics-tutorials/tree/main/generative-ai)課程。

**警告**  
使用 Kiro CLI 時，請先檢閱所有產生的內容和建議的動作，再繼續。提供意見回饋以改善回應品質，並符合您工作流程的需求。如需詳細資訊，請參閱 Kiro [的安全考量和最佳實務](https://docs.aws.amazon.com/kiro/latest/userguide/command-line-chat-security.html)。