How to solve 'V(D)J Chain detection failed' error on 10x Cloud

Question: I am analyzing V(D)J data on 10x Cloud and encounter the error 'V(D)J Chain detection failed'. How do I solve this error?

Answer: Explicitly set V(D)J chain type on 10x Cloud. The way to do this differs depending on whether the analysis is cellranger vdj or cellranger multi.

When running cellranger vdj on Cloud

For V(D)J-only analyses, run cellranger vdj. Select chain type under the Advanced settings. Click on the View advanced settings button to expand the options. 

Then, in the Chain section, use the dropdown menu to select either T cell receptors or B cell receptors.

When running cellranger multi on Cloud

For V(D)J data with gene expression data, preprocess the data jointly with cellranger multi. Here, the FASTQ library type label enables the explicit chain type selection. Under Library or Feature Type, select one of the three explicit V(D)J chain types from the dropdown menu--T (Alpha Beta), T (Gamma Delta) or B. Do not select Single Cell V(D)J, which calls the automatic detection protocol.

Brief discussion

By default, Cell Ranger will try to automatically determine the chain type from the data. When this fails, the complete error message will look something like the following. In order for Cell Ranger to automatically determine chain type, the sample library must meet the listed conditions.

V(D)J Chain detection failed for Sample foo in "/mnt/scratch/inputs/x/y".

Total Reads          = 1000000
Reads mapped to TR   = 49211
Reads mapped to IG   = 3

In order to distinguish between the TR and the IG chain the following conditions need to be satisfied:
- A minimum of 10000 total reads
- A minimum of 5.0% of the total reads needs to map to TR or IG
- The number of reads mapped to TR should be at least 3.0x compared to the number of reads mapped to IG or vice versa
Please check the input data and/or specify the chain via the --chain argument.

To overcome this error on the command line, for cellranger vdj explicitly set the --chain parameter to either IG for BCRs or TR for TCRs. Documentation is at https://support.10xgenomics.com/single-cell-vdj/software/pipelines/latest/using/vdj#opt-arg-exp. For cellranger multi, specify the chain type under the feature_types column in the multi config CSV's libraries section. Choices are VDJ-B for BCRs, VDJ-T for alpha-beta TCRs or VDJ-T-GD for delta-gamma TCRs. Documentation is at https://support.10xgenomics.com/single-cell-vdj/software/pipelines/latest/using/multi#config.

• Delta-gamma analysis is only available with cellranger multi and is officially unsupported although enabled. See Can I detect T cells with gamma-delta chains in my V(D)J data? for details.

If the immune cells are a small proportion of the sample cell population then this error may be expected. If this is not expected, or if immune cells were enriched by sorting, then please contact support@10xgenomics.com for a sample prep consult and attach the Cell Ranger web summary report and cDNA and library traces. 

10x Genomics Cloud Analysis is only available in the United States and Canada.

Products: 10x Genomics Cloud Analysis