Troubleshooting

The following sections provide resolutions to common problems that can occur when using Bases2Fastq. If a problem persists, contact Element Technical Support.

Correcting a Run Manifest

If you discover an issue with your run manifest, you can create a corrected run manifest and reexecute with the --run-manifest or -r optional argument.

The Getting Started with Bases2Fastq tutorial includes an example scenario for correcting a run manifest.

Verify a Corrected Run Manifest

To ensure that a corrected run manifest can successfully generate FASTQ files, add both the --qc-only and -r arguments to the Bases2Fastq command. The QC-only argument generates a representative view of run metrics on one tile to confirm a successful sample assignment.

bases2fastq /input /output -r /input/<corrected_manifest_filename.csv> --qc-only

Empty Index Sequences

An N base call indicates an unidentified nucleotide. If the Index 1 or Index 2 FASTQ files only contain sequences of N, the run base calls for index cycles might have quality issues. Contact Element Technical Support to troubleshoot.

The following explanations can cause index base call quality issues:

• Incorrect workflow primers (e.g., Adept primers instead of Elevate primers)
• Library quality issues
• Missing custom primers

Example All N Calls for Index Read 1 in I1_Fastq.fastq

@AVDEMOSN:DemoRunName:FLOWCELL123456:1:10201:0000:0015 1:N:0:NNNNNNNNN+NNNNNNNNN
NNNNNNNNN
+
!!!!!!!!!
@AVDEMOSN:DemoRunName:FLOWCELL123456:1:10201:0000:0035 1:N:0:NNNNNNNNN+NNNNNNNNN
NNNNNNNNN
+
!!!!!!!!!
...

Indexing Performance

If indexing performance does not meet specifications, complete the following actions to examine potential causes.

Review the HTML QC Report

Review the index charts in the HTML QC report and use the information to correct the run manifest or QC-fail the sequencing run. The charts show the index assignment percentage rate, the number of polonies assigned to each index sequence pair, and the most frequently unassigned indexes.

Review the PhiX Control Index Sequences

Spiking in PhiX Control Library without recording the index sequences affects index assignment. Make sure the run manifest includes the PhiX Control Library index sequences.

Review the Orientation of Index Sequences

Bases2Fastq might assign indexes incorrectly if the run manifest contains index sequences with conflicting index orientations. All samples, including PhiX Control Library and library pools, must use the same orientation for each index sequence in a column for Index 1 or Index 2.

You can review the observed orientation of index sequences relative to the orientation recorded in the Index 1 or Index 2 columns of the run manifest. Examine the I1IsReverseComplement and I2IsReverseComplement metrics in the RunStats.json output file. If the fields indicate a mismatch, some index sequences might have mismatching orientations that you must correct in the run manifest.

Mixed Observed Orientation in RunStats.json

{
  "AnalysisID": "1e51ac1a5abddd1f9b81a47219bbfcc5",
  "AnalysisVersion": "1.8.0.1260801529",
  "AssignedYield": 0.014859308,
  "FileVersion": "0.1.0",
  "FlowCellID": "FLOWCELL123456",
  "Lanes": [
    {
      "AssignedYield": 0.005960902,
      "I1IsReverseComplement": true,
      "I2IsReverseComplement": false,
      "Lane": 1,
...
}

Missing Flow Cell ID

If the flow cell ID is missing from the RunParameters.json file, a barcode scan likely failed during sequencing. Bases2Fastq logs a warning and uses a placeholder value in the header of the FASTQ files. Reexecute Bases2Fastq with the --flowcell-id argument to populate the correct flow cell ID.

The following example FASTQ file header uses FC- and the universally unique identifier for the run.

@P2-05:Dual-Index-Sim:FC-63067cc132ed49903b8af99e:1:10201:0000:0015 1:N:0:GCTACACGT+TGCACTAGC
TACTGGTGATTGGTGCTAACGATACGGTTAACCCGGCGGCGCAGGATGATCCGAAGAGACCGATTGCTGGTATGCCTGTGCTGGAAGTGTGGAAAGCGCAGAACGTGATTGTCTTTAAACGTTCTATGAACACTGGCTATG
+
& ? &',I=L:-'>'-+#AG1-8.=&#7@O@N4H>P#N0@IBC$&8J1IB=";8GACBH:4.38@D7B)H4CI2B%59&((G/NB#"M9,7:HI/8)HNFB<I(4GI?&E;P,0-4<%04+DD&46&459:38/2I);N@?05E(

Missing or Invalid Run Data

Upon encountering a bases file that has been copied or generated incorrectly, Bases2Fastq logs an error and stops the execution. To skip the file, reexecute Bases2Fastq with the --no-error-on-missing optional argument.

Invalid data errors include the following examples:

• gzip decompression error: INSUFFICIENT SPACE
• gzip decompression error: BAD DATA

Caution:

Recurring instances of corrupted Bases2Fastq data can indicate that an AVITI System requires service. Contact Element Technical Support to troubleshoot repeated cases of corrupted data.

Reducing Execution Time

If you encounter slow executions, use the --num-threads or -p optional argument to increase the number of CPU cores available for processing. A greater -p value allows for faster overall execution times, and you can use up to the total number of CPUs for your system.

Secondary Analysis File Compatibility

You can use optional arguments to make Bases2Fastq output files compatible with different options for secondary analysis.

• If secondary analysis requires a file naming convention similar to SampleName_S1_L001_R1_001.fastq.gz, apply --legacy-fastq to your execution.
• If a single-indexed library requires Index 2 FASTQ files for secondary analysis, use --settings to apply the following run manifest settings:
  • I2Mask,I2:N*
  • UmiMask,I2:Y*
  • UmiFastQ,True

Unassigned Samples

When you do not include samples or associated index sequences in your run manifest, Bases2Fastq assigns all reads to DefaultSample and creates the FASTQ files DefaultSample_R1.fastq.gz and DefaultSample_R2.fastq.gz. When you only include PhiX Control samples and index sequences or omit the index sequences for samples, Bases2Fastq creates Unassigned_R1.fastq.gz and Unassigned_R2.fastq.gz files.

If you include index sequences for your samples but receive unassigned or default FASTQ files, follow the guidance for troubleshooting Indexing Performance.

Error and Warning Messages

The following table describes the causes and resolutions for some of the common error and warning messages that can appear during a Bases2Fastq execution.

Message	Cause	Resolution
Invalid number of positional args: <#>, expected <#>	The interpretation of arguments passed to the execution differs from the expected string to parse. The execution command might contain an invalid argument input or a misplaced character, such as a space, comma, quotation mark.	Review the optional arguments for accuracy and placement of input values. If necessary, contact Element Technical Support.
[warning] main->CommandLineArgs: Automatic override: --legacy-fastq takes precedence over --split-lanes [warning] main: Both --legacy-fastq and --split-lanes are specified, defaulting to legacy file names.	The execution uses both the --legacy-fastq and --split-lanes optional arguments, which is redundant.	Update the execution command to only use --legacy-fastq.
[warning] Empty flowcell ID in RunParameters.json. Using "UNKNOWN_FLOWCELL" for flowcell ID field in FASTQ read IDs.	The flow cell ID is missing from the RunParameters.json input file. A barcode scan failure might have occurred during sequencing.	Use the --flowcell-id argument to manually enter a flow cell ID. For more information, see Missing Flow Cell ID.
[warning] Unable to find a suitable tile for parameter estimation in <lane number>. `[warning] Unable to deduce index read orientation in <lane number>. Assuming orientation implied by I1/I2 sequences in run manifest is correct.	While attempting to detect adapter sequences or index orientation, Bases2Fastq did not identify a reference region, which requires > 70% PF.	Make sure all parameters, adapters, or index sequences are in the correct orientation. Use the --force-index-orientation optional argument to make sure you use the index sequences as written in the run manifest.
terminate called after throwing an instance of 'std::runtime_error' what(): <filename> doesn't exist: </path/to/output>	A required input file is missing.	Ensure the input directory in the Bases2Fastq execution command is correct. Confirm that all input files are present in the input directory for the execution.
terminate called after throwing an instance of 'std::out_of_range'' what(): _Map_base::at	The separator for sequences in the run manifest file is incorrect.	Update the run manifest to use - as a separator. For example, use R1Adapter,AAAA-CCCCC-TTTT instead of R1Adapter,AAAA+CCCCC+TTTT.
filesystem error: cannot remove all: Unknown error 523 [</path/to/output/>]	To operate, Bases2Fastq deletes existing files in output directories and creates directories for output files. The user account on the operating system does not have permission to edit the target directory for output files.	Make sure all output files from previous executions are not open. Ensure the user account on your operating system has write permissions.
what(): filesystem error: cannot create directories: Permission denied [output/info/] Aborted (core dumped)	The user account on the operating system does not have permission to edit the target directory for output files.	Make sure all output files from previous executions are not open. Ensure the user account on your operating system has write permissions.
errors processing file: error on line(s) [-1], Preparation method () is invalid. Valid preparation methods are [AVAIABLE WORKFLOWS].	The current version of Bases2Fastq is incompatible with the AVITI OS version for the run.	Install a compatible version of Bases2Fastq.
[error] Run manifest error: There was an index collision with I1MismatchThreshold (1) and I2MismatchThreshold (1) on lane (2) for Sample [NAME] and Sample [NAME]. Reduce the MismatchThreshold setting(s) or modify the index sequences.	The index sequences for two samples in the run manifest are too similar. The default MismatchThreshold for Bases2Fastq is 1 bp.	Adjust the I1MismatchThreshold and I2MismatchThreshold settings. You can create a corrected run manifest with the new settings and reexecute, or you can use the --settings argument to reexecute with new run manifest settings.