Error parsing read "Cannot read field "regions" because "<local6>" is null'" when aligning concatenated single-end amplicon sequences with virtual paired-end input

[biomaticss]

Hi MiXCR team,
I am using MiXCR 4.7.0 to analyze concatenated antibody sequences (VH + (G4S)3 linker + VK) from a native pairing experiment. These are single-end long sequences (no real paired-end data), so I created a virtual R2 FASTQ file by copying the R1 file (sequences identical, quality all "I").
Command used:
mixcr -Xmx500g align \ --preset generic-amplicon \ --species hsa \ --rna \ --assemble-clonotypes-by CDR3 \ -OsaveOriginalReads=true \ -OallowPartialAlignments=true \ --floating-left-alignment-boundary VEND \ --rigid-right-alignment-boundary JBegin \ --report "${OUTPUT_ROOT}/mixcr/${SAMPLE}_concat_exact_align_report.txt" \ "$CONCAT_FASTQ" "$CONCAT_FASTQ_R2" "${OUTPUT_ROOT}/mixcr/${SAMPLE}_concat_exact.vdjca"
However, the alignment fails immediately with the following error
The full stacktrace is attached below (or in the log).
The FASTQ files look like this (example entry):
@pair_00000001_BC1_XXXX_BC3_YYYY_BC2_ZZZZ CAGGTGCAGCTGGTGGAGTCTGGGGGAGGCTTGGTACAGCCTGGGGGG...GGGGSGGGGSGGGGS...CAGGTGCAGCTGGTGGAGTCTGGGGGAGGCTTGGTACAGCCTGGGGGG + IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII
Both R1 and R2 have identical sequence and quality lines (all "I", length matches sequence).
This setup works fine with older MiXCR versions or when using single-end mode, but in 4.7.0 it throws the "Unknown letter '73'" error during read parsing.
Is this a bug in the FASTQ parser when handling identical paired reads, or am I missing a required parameter for single-end-like analysis of concatenated sequences?
Any advice on how to properly run MiXCR on such concatenated amplicons would be greatly appreciated!
Thanks in advance!
MiXCR version: 4.7.0
Java version: 21.0.6
OS: Linux
Full error log:
Please copy the following information along with the stacktrace: Version: 4.7.0; built=Wed Aug 07 19:19:48 UTC 2024; rev=976ba14139; lib=repseqio.v5.1 OS: Linux Java: 21.0.6 Abs path: /home/project Cmd args: align --preset generic-amplicon --species hsa --rna --assemble-clonotypes-by CDR3 -OsaveOriginalReads=true -OallowPartialAlignments=true --floating-left-alignment-boundary VEND --rigid-right-alignment-boundary JBegin -OmergerParameters.minimalOverlap=10 -OmergerParameters.minimalIdentity=0.9 --report results/1547/mixcr/1547_concat_exact_align_report.txt results/1547/fastq/1547_concatenated_exact_match.fastq results/1547/fastq/1547_concatenated_R2.fastq results/1547/mixcr/1547_concat_exact.vdjca picocli.CommandLine$ExecutionException: Error while running command align java.lang.NullPointerException: Cannot read field "regions" because "<local6>" is null at com.milaboratory.mixcr.cli.Main.registerExceptionHandlers$lambda-17(SourceFile:420) at picocli.CommandLine.execute(CommandLine.java:2088) at com.milaboratory.mixcr.cli.Main.execute(SourceFile:105) at com.milaboratory.mixcr.cli.Main.main(SourceFile:101) Caused by: java.lang.NullPointerException: Cannot read field "regions" because "<local6>" is null at io.repseq.core.GeneFeature.<init>(SourceFile:232) at io.repseq.core.GeneFeature.intersection(SourceFile:416) at io.repseq.core.GeneFeature.intersection(SourceFile:382) at com.milaboratory.o.jC.a(SourceFile:63) at com.milaboratory.o.jC.a(SourceFile:44) at com.milaboratory.mixcr.cli.CommandAssemble.validateParams(SourceFile:1040) at com.milaboratory.mixcr.cli.MiXCRParamsResolver.validateBundle(SourceFile:60) at com.milaboratory.mixcr.cli.MiXCRParamsResolver.validateBundle(SourceFile:38) at com.milaboratory.o.w.resolve(SourceFile:180) at com.milaboratory.o.w.resolve$default(SourceFile:171) at com.milaboratory.mixcr.cli.CommandAlign$Cmd$bpPair$2.invoke(SourceFile:922) at com.milaboratory.mixcr.cli.CommandAlign$Cmd$bpPair$2.invoke(SourceFile:922) at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74) at com.milaboratory.mixcr.cli.CommandAlign$Cmd.getBpPair(SourceFile:922) at com.milaboratory.mixcr.cli.CommandAlign$Cmd.access$getBpPair(SourceFile:728) at com.milaboratory.mixcr.cli.CommandAlign$Cmd$cmdParams$2.invoke(SourceFile:925) at com.milaboratory.mixcr.cli.CommandAlign$Cmd$cmdParams$2.invoke(SourceFile:924) at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74) at com.milaboratory.mixcr.cli.CommandAlign$Cmd.getCmdParams(SourceFile:924) at com.milaboratory.mixcr.cli.CommandAlign$Cmd.validate(SourceFile:1144) at com.milaboratory.mixcr.cli.MiXCRCommand.run(SourceFile:35) at picocli.CommandLine.executeUserObject(CommandLine.java:1939) at picocli.CommandLine.access$1300(CommandLine.java:145) at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2358) at picocli.CommandLine$RunLast.handle(CommandLine.java:2352) at picocli.CommandLine$RunLast.handle(CommandLine.java:2314) at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2179) at picocli.CommandLine$RunLast.execute(CommandLine.java:2316) at com.milaboratory.mixcr.cli.Main.registerLogger$lambda-32(SourceFile:539) at picocli.CommandLine.execute(CommandLine.java:2078) ... 2 more

[mizraelson]

Hi, I would highly recommend using our latest software Platforma for this data as it can handle such libraries without any preprocessing of FASTQ files giving you exactly the output you expect. You can follow this guide

[biomaticss]

Thank you for your reply. However, my data volume is extremely large and I want to run it on a server. Do you have any good suggestions?

[mizraelson]

Yes, Platforma can easily run on your server. Do you have an SSH access to the server? You can use this guide for the details.

[biomaticss]

Thank you very much for your response. There are limitations in this regard that prevent me from using it. I would like to ask if MixCR can annotate such VH-VK tandem sequences?

[mizraelson]

If you want to use MiXCR, the best approach is to use a tagPattern to first analyze the sequences before the linker and export the alignments with read headers. Then, use another pattern that only takes the part after the linker and export those results again with the read headers. Finally, you can merge the tables by the read header to obtain paired results.