# Troubleshooting ## General Troubleshooting on Standalone DRAGEN Server | Failure Type | Actions | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Software |

- Open the log file ./\/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 ./\/errors. The workflow creates an error file, error\_\.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\_\\_\.json. These files contain the command and stdout and stderr from the step.

| | Samples | Open the combined metrics output results file `.//Results//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 `.//Logs_Intermediates` to identify potential sources of error. | ## Sample Sheet Validation Failures In DRAGEN TruSight Oncology 500 ctDNA 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 `//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](https://help.tso500software.illumina.com/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements) 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. | | Sample Sheet is not in v2 format | Verify that the format of the sample sheet is v2. v1 sample sheet is not compatible with DRAGEN TruSight Oncology 500 ctDNA 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 index combinations: | Assay | Index Set ID | | ---------------- | --------------------------------- | | TSO 500 ctDNA |
  • UP1-UP16
| | TSO 500 ctDNA v2 |
  • 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 sections and fields are present in the sample sheet and follow the individual rules in [Sample Sheet Requirements](https://help.tso500software.illumina.com/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements) | ### Troubleshooting FASTQs issues: | Failure Type | Action | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Unique sample IDs | Verify that the Sample\_IDs are unique in the sample sheet. | | Incorrect folder structure | Verify that the FASTQ files are in the correct structure. Refer to [Starting From FASTQ Files](https://help.tso500software.illumina.com/dragen-tso-500-ctdna-guides/launching-analysis/analysis-launch-on-standalone-dragen-server/command-line-options#starting-from-fastq-files) for more information. | | Invalid FASTQ input files | If the FASTQs are invalid, start TSO 500 ctDNA analysis from BCL files. | ## Other Troubleshooting Tips | Failure Type | Action | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The output file directory contains information from previous analyses |

If this issue is seen: specify a new target output folder and repeat analysis

To prevent this issue: specify an empty directory before starting analysis

| | Single exon (single probe) genes are still reported in the CNV VCF file, but not the CNV TSV file |

No action needed; software is working as expected.

Currently all single probe genes are not emitted to the Copy Number Variants section of our CombinedVariantOutput.tsv. However, you can still find these events in the cnv.vcf.gz.

Due to the single probe nature, accurate CNV calling has not been validated and as such they are emitted as REF

| | Testing of cell lines, contrived samples and commercial controls does not return expected results | Review recommendations for using these samples types [here](https://help.tso500software.illumina.com/performance-testing/contrived-and-cell-line-sample-considerations). | ## Troubleshooting on ICA In addition to TSO 500 managed sample sheet validations, ICA managed TSO 500 errors include the following: | Error | Description | | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Failure type: ValueError: Could not find pipeline ID for app BCLConvert in sample sheet SampleSheet.csv | Action: Ensure StartsFromFastq field is in the \[TSO500L\_Settings] section, and it is not present in the \[BCLConvert\_Settings] Section. Refer to [Sample Sheet Requirements](https://help.tso500software.illumina.com/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/run-planning/sample-sheet-requirements) for more information. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.tso500software.illumina.com/dragen-tso-500-ctdna-guides/dragen-tso-500-ctdna-v2.6/troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.