Troubleshooting

Failure Type	Actions
Software	- Open the log file ./<AnalysisFolder>/Logs_Intermediates/pipeline_trace.txt. This log file displays each pipeline step run by the Nextflow workflow manager software. If a step fails, it is marked as FAILED. Each step generates log files that are stored in step-specific subfolders in the Logs_Intermediates folder. Review the log files in the relevant Logs_Intermediates folder for the step to identify potential sources of error. - Open the errors folder ./<AnalysisFolder>/errors. The workflow creates an error file, error_<NameOfFailedStep>.json, for each step that failed during analysis. For steps that fail per sample, there is a separately labeled file for each sample that failed each step error_<NameOfFailedStep>_<SampleIDIfRelevant>.json. These files contain the command and stdout and stderr from the step.
Samples	Open the combined metrics output results file ./<AnalysisFolder>/Results/<PairId>/MetricsOutput.tsv. If a sample fails an analysis step, the Pair ID that contains the sample shows the failure under FAILED_STEPS in the Analysis Status section, and COMPLETED_ALL_STEPS shows as False. If available, review the individual log files for the failed steps under ./<AnalysisFolder>/Logs_Intermediates to identify potential sources of error.
Multinode Gather	If the following error appears, check if the sample or pair ID was included multiple times during separate node analysis runs, before being gathered together. If the error exists, rerun one of the analyses without the duplicate and reattempt gathering. ERROR:Gather:Destination file ... already exists - check if the same sample ID is in multiple input folders

Sample Sheet Validation Failures

In DRAGEN TruSight Oncology 500 Analysis Software, the analysis fails if a sample sheet is invalid. If an invalid sample sheet in suspected, log files can help troubleshoot a failed analysis. Use the following steps to find the log file for the sample sheet:

1. Navigate to the following location /<analysis_output>/Logs_Intermediates/SamplesheetValidation.

2. Open the SamplesheetValidation-.log file

3. Find a line with the following: SampleSheetValidationTask:NA:1 exited with return code 1 which has not been declared as a valid return code.

4. Search for errors in the sample sheet validation log and compare with the guidelines and warnings in [Sample Sheet Requirements](add link) and the following tables.

General troubleshooting for a failed sample sheet

Failure Type	Action
Sample Sheet not found	Verify that SampleSheet.csv is present at the top level of the run folder with the name "SampleSheet.csv". If the sample sheet is in a different location, supply the sample sheet using the --sampleSheet option
Indexes are not valid for the sequencer and/or assay	See Valid indexes for assay and instrument combinations for correct indexes for the sequencer and assay.
Pair_ID is not unique	Pair_ID column is required in the TSO500S_Data section of the sample sheet, which pairs at most one RNA and one DNA sample together for analysis. If the sample does not have a pair, use a unique pair ID for single samples.
Sample Sheet Not in v2 Format	Verify that the format of the sample sheet is in v2 format. v1 sample sheet is not compatible with DRAGEN TruSight Oncology 500 Analysis Software.
Analysis does not run	Verify the analysis starts from the run folder, and BCLs or FASTQs are in the correct locations as outlined in Starting From BCL Files and Starting From FASTQ Files respectively.

Valid indexes for assay and instrument combinations

Assay	NextSeq 550	NextSeq 550
TSO 500	- UP1-UP16 - CP1-CP16 (DNA Only)	- UP1–UP16
TSO 500 HT	UDP0001–UDP0192	UDP0001–UDP0192

Troubleshooting BCL issues

Failure Type	Action
Lane Column without Values	Ensure that the column is completed. If lane is not applicable to the run, delete the column.
Format of v2 sample sheet is incorrect	Verify that the following sections and fields are present in the sample sheet and follow the individual rules in [Sample Sheet Requirements](Add Link to SS requirements). [BCLConvert_Settings] - SoftwareVersion - AdapterRead1 - AdapterRead2 - AdapterBehavior - MinimumTrimmedReadLength - MaskShortReads [BCLConvert_Data] - Sample_ID - index - index2 [TS0500S_Data] - Sample_ID - Index_ID - Sample_Type - Pair_ID
HRD analysis is missing	Make sure that HRD is in the correct column in the sample sheet. Refer to Sample Sheet Requirements for more information.

Troubleshooting FASTQ issues

Failure Type	Action
Sample_ID and/or Sample_Type is not present	Verify that the sample sheet has columns and values for Sample_ID and Sample_Type.
Unique sample IDs	Verify that the Sample_IDs are unique in the sample sheet.
Format of v2 Sample Sheet is incorrect	Verify that the following sections and fields are present in the sample sheet and follow the individual rules in Sample Sheet Requirements. [TS0500S_Data] - Sample_ID - Index_ID - Sample_Type - Pair_ID Make sure that HRD, if needed, is in the correct column in the sample sheet. Refer to Sample Sheet Requirements for more information.
Incorrect folder structure	Verify that the FASTQ files are in the correct structure. Refer to Starting From FASTQ Files for more information.
Invalid FASTQ input files	If the FASTQs are invalid, start TSO 500 analysis from BCL files.
HRD analysis missing	Make sure that HRD is in the correct column in the sample sheet.