refineTagsAndSort error for PacBio single-cell BCR data

[freshtuo]

Hi MiXCR team,

I’m running PacBio single-cell BCR (CB+UMI+BCR in one single-end FASTQ) with MiXCR and hitting a persistent error during tag refinement.

Context:

• MiXCR: v4.7.0
• OS: Linux | Java: 24.0.1
• Command:

mixcr refineTagsAndSort \
  --dont-correct-tag-with-name CELL \
  --report refine.report.txt \
  alignments.vdjca refined.vdjca

• Tag pattern used at align:
  --tag-pattern "^(CELL:N{16})(UMI:N{12})(R1:*)"
• CELL barcodes already corrected upstream; I only want UMI correction per cell.

Error:

picocli.CommandLine$ExecutionException: Error while running command refineTagsAndSort
com.milaboratory.mixcr.cli.TagCorrectionError: Error on tag correction of [UMI]
Caused by: java.lang.IllegalArgumentException: Unexpected filter tag request. Requested UMI but next level is CELL.

Console banner confirms only UMI is being corrected:

Correction will be applied to the following tags: UMI
Sorting will be applied to the following tags: CELL, UMI

Could you help troubleshoot? is there a known fix/workaround for the “Requested UMI but next level is CELL” error in refineTagsAndSort when doing UMI-only correction under this tag pattern?

Thanks so much for your help!!

Tuo

[mizraelson]

Hi Tuo,
Can you please try using the latest develop version and let me know if the error persists.
If it does, please share the command you used for mixcr align, and the .vdjca file if possible.

Sincerely,
Mark

[freshtuo]

Hi Mark,

Thank you very much for your quick reply and for sharing the develop version. I tested it, but unfortunately I still get the same error.

Let me provide some more context about my data and the steps I’ve taken, as I suspect I may not be running MiXCR in a proper way.

• Library prep / sequencing: The data comes from a 10x Genomics single-cell multiome library, where from the cDNA we specifically enriched the BCR portion and sequenced it on PacBio long-read platform.

• Preprocessing: I processed the raw long-read data with the PacBio's Isoseq pipeline to remove adapters, tag cell barcodes and UMI barcodes, and perform cell barcode correction.

• FASTQ conversion: After preprocessing, I prepared a FASTQ file (single-end) for MiXCR, in which each read has the structure: CELL+UMI+BCR.

• MiXCR alignment: I ran alignment with the following command:

mixcr align \
  --preset generic-pacbio-with-umi \
  --species hsa \
  --tag-pattern "^(CELL:N{16})(UMI:N{12})(R1:*)" \
  --assemble-clonotypes-by CDR3 \
  --split-clones-by V \
  --split-clones-by J \
  --report test.align.report.txt \
  --threads 16 \
  test.fastq.gz test.vdjca

This step finishes successfully.

• Tag refinement: This step failed:

mixcr refineTagsAndSort \
  --dont-correct-tag-with-name CELL \
  --report refine.report.txt \
  test.vdjca refined.vdjca

Error:

   Version: 4.7.0; built=Wed Aug 07 15:19:48 EDT 2024; rev=976ba14139; lib=repseqio.v5.1
        OS: Linux
      Java: 24.0.1-internal
  Abs path: /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327
  Cmd args: refineTagsAndSort --dont-correct --report /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327/info/step_8.run_mixcr_umi/test.refine.report.txt /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327/info/step_8.run_mixcr_umi/test.vdjca /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327/info/step_8.run_mixcr_umi/test.refined.vdjca
picocli.CommandLine$ExecutionException: Error while running command refineTagsAndSort com.milaboratory.mixcr.cli.TagCorrectionError: Error on tag correction of []
        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: com.milaboratory.mixcr.cli.TagCorrectionError: Error on tag correction of []
        at com.milaboratory.mixcr.cli.CommandRefineTagsAndSort$Cmd.run1(SourceFile:375)
        at com.milaboratory.mixcr.cli.MiXCRCommandWithOutputs.run0(SourceFile:69)
        at com.milaboratory.mixcr.cli.MiXCRCommand.run(SourceFile:37)
        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
Caused by: java.lang.IllegalArgumentException: Unexpected filter tag request. Requested UMI but next level is CELL.
        at com.milaboratory.o.gn$b.getKeyExtractor(SourceFile:957)
        at com.milaboratory.mitool.refinement.gfilter.KeyedFilterContext.getKeyExtractor(SourceFile:97)
        at com.milaboratory.mitool.refinement.gfilter.GroupFilter.filter(SourceFile:297)
        at com.milaboratory.o.gn.g(SourceFile:654)
        at com.milaboratory.o.gn.c(SourceFile:473)
        at com.milaboratory.mixcr.cli.CommandRefineTagsAndSort$Cmd.run1(SourceFile:373)
        ... 13 more

• Assembly attempt: I also tried to skip refineTagsAndSort and went directly to assemble:

mixcr assemble \
  --report test.assemble.report.txt \
  --assemble-clonotypes-by CDR3 \
  --split-clones-by V \
  --split-clones-by J \
  test.vdjca test.clns

it failed with error:

   Version: 4.7.0; built=Wed Aug 07 15:19:48 EDT 2024; rev=976ba14139; lib=repseqio.v5.1
        OS: Linux
      Java: 24.0.1-internal
  Abs path: /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327
  Cmd args: assemble --report /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327/info/step_8.run_mixcr_umi/test.assemble.report.txt --assemble-clonotypes-by CDR3 --split-clones-by V --split-clones-by J /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327/info/step_8.run_mixcr_umi/test.vdjca /gc11-data/analysis/taz2008/project/scRNAseq/PacBio_scBCR_Wilson-JM-19327/info/step_8.run_mixcr_umi/test.clns
picocli.CommandLine$ExecutionException: Error while running command assemble java.lang.IllegalArgumentException: Input file has insufficient sorting level
        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.IllegalArgumentException: Input file has insufficient sorting level
        at com.milaboratory.o.iJ.<init>(SourceFile:55)
        at com.milaboratory.mixcr.cli.CommandAssemble$Cmd.run1(SourceFile:326)
        at com.milaboratory.mixcr.cli.MiXCRCommandWithOutputs.run0(SourceFile:69)
        at com.milaboratory.mixcr.cli.MiXCRCommand.run(SourceFile:37)
        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

I was trying to use the most relevant preset I could find, generic-pacbio-with-umi, but I’m not sure if this is appropriate for single-cell BCR data in my case. Could you suggest or guide me on the proper way to run MiXCR for this type of data? Many thanks!

Best,
Tuo

[mizraelson]

I see, you are using the generic-pacbio-with-umi preset that does not include CELL barcodes. Could you try the following instead generic-ht-single-cell-amplicon-with-umi

[freshtuo]

Hi Mark,

Thank you for the suggestion to switch preset from generic-pacbio-with-umi to generic-ht-single-cell-amplicon-with-umi, which resolved the earlier issue but triggered a new one at the assembleCells step. I summarized my workflow and commands below:

• Input:

PacBio long read data.
Single-end FASTQ file, each read represents a full-length BCR transcript.
I manually appended cell barcode and UMI in front of each read (CELL:N{16} UMI:N{12} BCR:N*).

• Commands:

1. Align

mixcr align --preset generic-ht-single-cell-amplicon-with-umi \
  --species hsa \
  --tag-pattern "^(CELL:N{16})(UMI:N{12})(R1:*)" \
  --floating-left-alignment-boundary FR1Begin \
  --floating-right-alignment-boundary C \
  --assemble-clonotypes-by CDR3 \
  --split-clones-by V --split-clones-by J \
  --report out.align.report.txt --threads 8 \
  input.fastq.gz out.vdjca

2. Refine tags and sort (correct UMI only since cell barcodes already corrected)

mixcr -Xmx100g refineTagsAndSort \
  --set-whitelist CELL=file:matched_cell_barcodes.txt \
  --dont-correct-tag-with-name CELL \
  --report out.refine.report.txt \
  out.vdjca out.refined.vdjca

3. Assemble

mixcr assemble --write-alignments \
  --report out.assemble.report.txt \
  --assemble-clonotypes-by CDR3 \
  --split-clones-by V --split-clones-by J \
  out.refined.vdjca out.clna

4. Assemble cells (fails here)

mixcr -Xmx100g assembleCells --report out.assembleCells.report.txt \
  out.clna out.grouped.clna

5. Assemble contigs (works if skipping step 4)

mixcr -Xmx100g assembleContigs \
  --report out.assembleContigs.report.txt \
  out.clna out.contigs.clns

6. export

mixcr exportClones --dont-split-files \ 
  --chains IGH,IGK,IGL \ 
  --split-by-tags CELL -tags CELL \ 
  -aaFeature CDR3 -nFeature VDJRegion \ 
  -nFeatureImputed VDJTranscript -isotype \ 
  -isProductive CDR3 -isOOF CDR3 -hasStops CDR3 \
  out.clna out.clonotypes.tsv; 

mixcr exportClones out.contigs.clns out.clones_contigs.tsv

• Error Message at step 4:

App version: 4.7.0-234-develop; built=Tue Sep 23 09:20:35 EDT 2025; rev=1196a91885; lib=repseqio.v6.3
Initialization: progress unknown
Parsing input: 63.6%
Parsing input: 100%  ETA: 00:00:00
Grouping clones: 0%
Grouping clones: 28%  ETA: 00:00:12
Grouping clones: 59.1%  ETA: 00:00:01
Grouping clones: 87.7%  ETA: 00:00:00
Grouping clones: 110.3%  ETA: 00:00:00
Overlapping leftover cells barcodes with found groups: 14.4%
Overlapping leftover cells barcodes with found groups: 100%  ETA: 00:00:00
Overlapping non functional clones with groups: 22.2%
Overlapping non functional clones with groups: 53.9%  ETA: 00:00:01
Overlapping non functional clones with groups: 100%  ETA: 00:00:00
Splitting clones by groups: 100%
Resorting and recalculating ranks
Writing output
java.lang.AssertionError: Assertion failed
        at com.milaboratory.o.jW.a(SourceFile:298)
        at com.milaboratory.mixcr.cli.CommandAssembleCells$Cmd.processClna(SourceFile:168)
        at com.milaboratory.mixcr.cli.CommandAssembleCells$Cmd.run1(SourceFile:116)
        at com.milaboratory.mixcr.cli.MiXCRCommandWithOutputs.run0(SourceFile:69)
        at com.milaboratory.mixcr.cli.MiXCRCommand.run(SourceFile:37)
        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:543)
        at picocli.CommandLine.execute(CommandLine.java:2078)
        at com.milaboratory.mixcr.cli.Main.execute(SourceFile:106)
        at com.milaboratory.mixcr.cli.Main.main(SourceFile:102)

Same error occurs with both the release (v4.7.0) and latest develop version you shared.

• Summary

1. Up to assemble, everything runs cleanly and reports look normal.
2. assembleCells starts grouping clones and reaches “Writing output” before crashing. I do have the output file "out.grouped.clna" with similar file size as the "out.clna" file, however, MiXCR reports it a corrupted file when I tried exportClones based on that file.
3. If I skip this step and go directly to assembleContigs, it completes successfully, but as expected I only get clone-level contigs — not per-cell per-clone assemblies.

I’m trying to obtain per-cell contigs (one heavy and one light per cell) from this long-read single-cell dataset. Could you please troubleshoot this issue? I’m happy to share a small toy dataset that reproduces the error if it helps with debugging. Many thanks!

Tuo

[mizraelson]

Hi, after running the Refine tags and sort command try the following:

mixcr assemble \
--report out.assemble.report.txt \
--assemble-clonotypes-by VDJRegion \
out.refined.vdjca \
out.clns

mixcr exportClones \ 
-isProductive CDR3 \
-isOOF CDR3 \
-hasStops CDR3 \
out.clns \
out.clonotypes.tsv; 

[freshtuo]

Hi Mark,

Thanks a lot for the helpful suggestion! I reran the pipeline following your suggestion and it completed successfully.

Based on my understanding, this partially resolves my original question. Using the entire VDJRegion makes the clonotype definition more stringent compared to using CDR3 only, which seems more appropriate for our long-read data.

From your comment, I assume that running assembleContigs would perform per-clonotype assembly and effectively eliminate any sequence variation that may exist across cells within the same clonotype, so skipping it makes sense in this context.

To give some additional background: we are working with single-cell PacBio BCR data and are trying to generate the longest-available consensus sequence per clonotype, ideally at the cell level. In our dataset, we observe more than one clonotype per cell, likely due to transcript leakage from highly immunoglobulin-expressing cells (such as plasma cells) that captured by other cells. This creates background signal where multiple clonotypes appear in the same cell.

That’s why I originally tried to run assembleCells followed by assembleContigs, hoping to reconstruct one consensus contig per cell × clonotype, which would allow us to better resolve these cases.

Do you have any suggestions on how best to achieve this — i.e., generating per-cell consensus (longest-available) sequences per clonotype — given our setup and the current behavior of assembleCells?

Thanks again for your time and support!

Best,
Tuo