Support homeCell Ranger
Cell Ranger Error Codes

Cell Ranger Error Codes

This page describes common errors encountered when running Cell Ranger. Some of these errors may also be applicable to other 10x pipelines (e.g., Cell Ranger ARC). To find a solution for a specific error, search this page for the error name or code.

If your error is not listed, or if the recommended steps do not resolve the issue, contact support@10xgenomics.com.

TXRNGR10001: There were not enough reads to auto-detect the chemistry: Sample test_sample in __PATH__

What it means

Cell Ranger automatically detects the assay chemistry by analyzing a small sample of reads from the input FASTQ files (the first 2 million reads). This error occurs when the total number of reads in the FASTQ files is below this threshold. This can happen for a few reasons. Before running the pipeline again, check the following:

  • Read Count: Confirm the number of reads in your FASTQ files. A FASTQ entry is four lines, so you can count the total lines and divide by four. For example:
wc -l your_file.fastq.gz | awk '{print $1/4}'
  • Sample Demultiplexing: Ensure the correct sample index was used when demultiplexing BCLs to generate the FASTQ files. An incorrect index can lead to very few reads for that sample.
  • File Integrity: Verify that the FASTQ files have not been trimmed, filtered, or otherwise pre-processed. 10x Genomics pipelines are designed to work with raw, unaltered FASTQ data.

Solutions

There are three potential paths to resolving this error, depending on your investigation of the root cause.

  • Manually specify chemistry: If the read count is low but you are confident the data is correct, you can bypass auto-detection by setting the --chemistry parameter. Refer to the cellranger count arguments page or the cellranger multi config CSV page for detailed instructions. You can find a list of all valid chemistry strings here.
  • Regenerate FASTQ files: If you discover an issue with how the FASTQ files were generated (e.g., the wrong sample index was used) or find that they were pre-processed, regenerate them and re-run the pipeline.
  • Increase sequencing depth: If the read count is low because the library was under-sequenced, you will need to sequence the library again to a greater depth to generate enough reads.

TXRNGR10002: An extremely low rate of correct barcodes was observed for all the candidate chemistry choices for the input: Sample <sample> in <path>. Please check your input data.

What it means

Cell Ranger identifies the assay chemistry by checking the barcodes in a sample of reads against a known “inclusion list” for each supported chemistry. This error means that an extremely low fraction of barcodes in your data matched any of the inclusion lists.

Essentially, the pipeline cannot figure out what kind of data it's looking at. You can learn more about the chemistry detection process in this article.

Common Causes

This error is often caused by a mismatch between the input data and the software pipeline. Check if your situation matches one of these common scenarios:

  • Unsupported data type: The input FASTQ files are from a non-10x Genomics platform or an unsupported 10x product (e.g., Single Cell ATAC, Visium Spatial). Cell Ranger is designed specifically for 10x Genomics single-cell gene expression and feature barcode products.
  • Incorrect pipeline used: You are using cellranger count for data that requires cellranger multi. For example, Single Cell Gene Expression Flex or Fixed RNA Profiling data must be analyzed with cellranger multi.
  • Outdated Cell Ranger version: You are analyzing data from a new chemistry (e.g., GEM-X) with an older version of Cell Ranger (e.g., v7) that was released before that chemistry was developed.
  • Poor sequencing quality: The base quality is critically low in the barcode region of the reads (e.g., the first 16 bases of R1, or the probe barcode region for Flex data). This prevents the pipeline from accurately identifying barcodes.

Solutions

Follow these steps to diagnose and resolve the issue.

  • Verify your data and pipeline choice. First, confirm the library preparation protocol that was used is on Cell Ranger’s supported libraries list. Then, use the Cell Ranger Pipeline Selector tool to confirm you are using the correct pipeline command (count vs. multi) for your assay.
  • Update Cell Ranger. If you are using a new chemistry, ensure you are using a compatible version of Cell Ranger. It is generally best practice to use the latest version, which you can download from the Cell Ranger Download Center.
  • Manually specify the chemistry. If you are certain your data type is supported but auto-detection is failing (e.g., due to low quality), you can bypass it with the --chemistry parameter.
    • Note for Multiome GEX: When analyzing only the Gene Expression library from a Multiome ATAC + GEX experiment, you must use this option and set --chemistry=ARC-v1. See this article and this article for more details.
    • See this page for a list of all valid chemistry options.
  • A Note on Non-10x Data: Cell Ranger is designed and licensed exclusively for data generated by 10x Genomics. Attempting to analyze data from other sources may produce errors and is a violation of the End-User License Agreement (EULA).

TXRNGR10003: Unable to distinguish between [<chemistry1>, <chemistry2>] chemistries based on the R2 read mapping for Sample <sample1>

What it means

Cell Ranger's automatic chemistry detection works by checking if the barcodes in your data match the known barcode inclusion lists for supported chemistries. This error means your data is a strong match for more than one chemistry, so the pipeline can't safely choose one on its own.

This often happens when a newer chemistry's barcode set is a superset of an older one. The pipeline recognizes both as valid possibilities and needs you to break the tie. You can learn more about the chemistry auto-detection algorithm in this article.

Solution

The solution is to explicitly tell Cell Ranger which chemistry to use.

  • Identify the correct chemistry. You will need to confirm exactly which assay was used for library preparation. The best places to check are your lab notebook, the product box the reagents came in, or by asking the person who prepared the library. The chemistry name is printed directly on the kit packaging.
  • Manually specify the chemistry. Once you know the correct chemistry, re-run the pipeline and add the --chemistry parameter to your command. You can find the correct chemistry option in this list.

TXRNGR10004: The read lengths are incompatible with all the chemistries for <sample1>

This error indicates that the read lengths in your FASTQ files are not compatible with the selected 10x Genomics chemistry for a given sample.

Root Cause

The primary cause of this error is incorrect read lengths in your FASTQ files. To investigate, you should first check the read length distribution for your R1 and R2 reads using a tool like FastQC.

Common reasons for incorrect read lengths include:

  • Improper Trimming: Reads were trimmed too short during demultiplexing or other preprocessing steps.
  • Swapped Reads: The R1, R2, or Index FASTQ files were assigned to the wrong input fields.
  • Incompatible Configuration: The sequencing run was set up with a configuration that doesn't match the library's chemistry requirements.
  • Corrupted Downloads: FASTQ files downloaded from a public database (like the SRA) may be incomplete or corrupted.

Next Steps

To resolve this error, you will need to correct the input FASTQ files.

  • Verify Read Lengths: Ensure your reads meet the minimum length requirements for the specific Chromium chemistry you used. You can find these specifications in the 10x Genomics Sequencing Handbook.
  • Regenerate FASTQs: If the reads were trimmed or the files were swapped, regenerate the FASTQ files from the original BCL data with the correct settings. We do not recommend trimming sequencing reads before running Cell Ranger.
  • Re-download Files: If you sourced the FASTQ files from a third-party database (e.g., SRA), try downloading them again to ensure the transfer was complete and the files are not corrupt.

TXRNGR10005: The read lengths are incompatible with all features described in the feature reference for Sample.

What it means

This error occurs when the length of the reads in your FASTQ file is shorter than the length required by the pattern field in your Feature Barcode reference CSV.

Cell Ranger uses this pattern to locate the Feature Barcode sequence (BC). The pattern is defined by Ns (random bases) and the (BC) section. The pipeline needs the read to be long enough to cover the entire pattern.

For example, consider this feature reference:

id,name,read,pattern,sequence,feature_type
sample,name,R2,^NNNNNNNNNN(BC)NNNNNNNNN,GTCTTTGTCAGTGCA,Antibody Capture

The minimum required read length is the sum of all bases in the pattern: 10 (leading Ns) + 15 (BC sequence) + 9 (trailing Ns) = 34 bp. If the R2 reads in your FASTQ file(s) are shorter than 34 bp, the pipeline will fail with this error.

Solutions

To resolve this, you either need to adjust the feature reference to match your reads or fix the reads to match your reference.

  • Modify the Feature Reference pattern. If your read length is fixed (e.g., 28 bp) and cannot be changed, you may be able to edit the pattern in your CSV file. By removing some of the Ns from the beginning or end of the pattern, you can reduce the minimum required read length.
    • Example: To accommodate 28 bp reads with the 15 bp barcode from the example above, you could change the pattern from ^NNNNNNNNNN(BC)NNNNNNNNN to ^NNNNNNNNNN(BC)NNN. This reduces the requirement to 10 + 15 + 3 = 28 bp.
  • Investigate your FASTQ files. If your feature reference is correct, you need to determine why your read lengths are shorter than required. Check the following:
    • Trimming: Were the FASTQ files trimmed or otherwise processed after generation? Cell Ranger is designed to start with raw, unaltered FASTQ data. If possible, use the original unprocessed files.
    • Sequencing Run Setup: Was the sequencing run configured to generate reads of the proper length for your assay?
    • File Integrity: If the files were downloaded from a database (e.g., SRA), a corrupted or incomplete download could be the cause. Try downloading them again.
    • Resequence: If the library was intentionally sequenced with reads that are too short for the assay, the solution is to re-sequence the library to a sufficient read length.

TXRNGR10006: Barcodes from the <librarytype1> library and the <librarytype2> library have insufficient overlap.

What it means

When you analyze multiple libraries from the same sample together (e.g., Gene Expression and Antibody Capture), Cell Ranger expects them to share a high percentage of cell barcodes because they were derived from the same single-cell suspension in a single GEM well.

This error indicates that the libraries you provided do not share enough common barcodes to be considered a matched pair from the same experiment.

Common Causes

Before attempting a software workaround, it's critical to investigate the root cause.

  • Mismatched Libraries: This is the most common reason. The libraries were generated from cells that were processed in different GEM wells and were incorrectly paired for analysis.
  • Low Read Quality: The R1 read, which contains the cell barcode, has poor base quality. You can assess this using a tool like FastQC.
  • Low Read Count: One of the libraries has too few reads to make a confident comparison (for example, a Feature Barcode library with fewer than 10,000 reads).
  • Poor Library Quality: One or both libraries are of poor quality (e.g., low complexity, high artifacts), resulting in few valid cell barcodes being detected.

Solution

First, verify that the libraries are a matched set from the same GEM well. Check your sample sheets and lab notes. If you discover they are mismatched, find the correct library pair to analyze.

If you are confident the libraries are a correct match but a quality issue is causing the error, you can disable this safety check as a last resort.

For Cell Ranger v7.0 and later: You can disable the check using the --check-library-compatibility=false option. For more details, refer to the pipeline arguments documentation. On the command line with cellranger count:

cellranger count --id=sample123 \
                 ... \
                 --check-library-compatibility=false
  • On the command line with cellranger multi: Add this line to the [gene-expression] section of your multi config CSV file:
check-library-compatibility,false

On 10x Genomics Cloud Analysis: In your pipeline setup, go to the Advanced Settings within the Gene Expression Settings section to find and disable this check.

For Cell Ranger v5 or v6 (Advanced): For these older versions, you can lower the similarity threshold. This requires editing a file within the Cell Ranger installation directory.

  • Locate the parameters.toml file inside your installation path (cellranger-x.y.z/lib/bin/).
  • Open the file and find the min_barcode_similarity parameter (default is 0.1).
  • Change the value to a number lower than the overlap reported in your error message.
  • Important: After your analysis is complete, you must change this value back to the default. Forgetting to do so will affect all subsequent pipeline runs on that machine.

TXRNGR10007: Barcodes from the [GeneExpression] library and the [VDJ] library have insufficient overlap.

What it means

When analyzing paired Gene Expression (GEX) and V(D)J libraries from the same sample with cellranger multi, the pipeline expects them to share a high percentage of cell barcodes. This is because both libraries were derived from the same pool of cells captured in a single GEM well.

This error indicates that the GEX and V(D)J libraries you provided do not share enough common barcodes to be considered a matched pair from the same experiment.

Common Causes

Before overriding this check, it is critical to investigate the potential root cause.

  • Mismatched Libraries: This is the most common reason. The GEX and V(D)J libraries were prepared from cells that were processed in different GEM wells and were incorrectly paired for analysis.
  • Low Read Quality: The R1 read, which contains the cell barcode, has poor base quality in one or both libraries. This can be assessed with a tool like FastQC.
  • Low Cell Recovery: One of the libraries may have had poor cell recovery, resulting in a low number of high-quality cell barcodes that can be confidently matched with the other library.
  • Poor Library Quality: One or both of the libraries are of poor overall quality (e.g., low complexity, high artifacts), leading to few valid cell barcodes being detected.

Solution

First, verify that the libraries are a matched set from the same GEM well. Check your sample sheets and lab notes to confirm their origin. If you discover they are mismatched, you must correct the input files to pair the correct libraries.

If you are confident the libraries are a correct match but a quality issue is causing the error, you can disable this safety check as a last resort.

On the command line with cellranger multi: Add the following line to the [gene-expression] section of your multi config CSV file. For more details, refer to the pipeline arguments documentation.

check-library-compatibility,false

On 10x Genomics Cloud Analysis: When setting up your analysis, go to the Advanced Settings for the Gene Expression Settings section. Find the Check library compatibility option and disable it.

TXRNGR10008: V(D)J Chain detection failed for <sample> in <outputpath>

Total Reads = <Totalreads> Reads mapped to TR = <TCRreads> Reads mapped to IG = <IGreads>

What it means

When analyzing a V(D)J library, Cell Ranger automatically determines whether it contains T-cell receptor (TR) or B-cell immunoglobulin (IG) chains. It does this by aligning a sample of reads to the V(D)J reference and checking if the library meets three specific criteria:

  • A minimum of 10,000 total reads must be present.
  • At least 5% of the total reads must map to either TR or IG reference genes.
  • The number of reads mapped to one chain type (e.g., TR) must be at least 3x the number of reads mapped to the other (e.g., IG), or vice versa.

This error occurs when your V(D)J library fails to meet one or more of these three conditions, preventing the pipeline from confidently identifying the chain type.

Common Causes

  • Incorrect Input Files: This is a frequent cause. A Gene Expression or Feature Barcode library was provided as input instead of a V(D)J library. The pipeline cannot find TR or IG sequences in non-V(D)J data.
  • Poor Library Quality: The V(D)J library itself may be of low quality, for example, due to poor enrichment of V(D)J transcripts during library preparation. This results in too few reads mapping to the TR or IG reference genes.
  • Poor Sequencing Quality: The R2 reads, which contain the V(D)J sequence information, have low base quality. This prevents reads from successfully aligning to the reference. You can use a tool like FastQC to assess read quality.

Solutions

  • Verify Your Input Files. Before trying other solutions, double-check that you have provided the correct V(D)J FASTQ files for analysis. Consult with your sequencing core if you are unsure which files to use.
  • Manually Specify the Chain Type. If you know the library type but auto-detection is failing due to a quality issue, you can bypass the error by manually specifying the chain. This allows the pipeline to complete and generate a web summary report, which you can then use to diagnose the underlying quality problem.
  • Assess Quality and Re-sequence. After bypassing the error using the step above, carefully review the web_summary.html file. If the QC metrics and/or FastQC results confirm that sequencing quality is poor across the entire run, you may need to re-sequence the V(D)J library.

TXRNGR10009: We detected a mixture of different R1 lengths ([{min}-{max}]), which breaks assumptions in how UMIs are tabulated and corrected.

What it means

Cell Ranger's UMI (Unique Molecular Identifier) counting and correction algorithms rely on a critical assumption: all R1 reads, which contain the cell barcode and UMI, must be the exact same length.

This error occurs when the pipeline scans your R1 FASTQ files and detects that the reads have varying lengths.

Common Causes

There are three common scenarios that produce FASTQ files with unequal R1 read lengths:

  • Adapter Trimming During Demultiplexing: The FASTQ files were generated (e.g., with Illumina's bcl2fastq or bcl-convert) with an option for adapter trimming enabled. Because not all reads contain an adapter sequence, this process results in a mix of trimmed and untrimmed read lengths.
  • Manual Pre-processing: The raw FASTQ files were trimmed or otherwise processed before being run through Cell Ranger.
  • Merging Data From Different Runs: FASTQ files from the same library were sequenced on different flow cells or in different runs using different R1 read length settings, and then merged together.

Solutions

The ideal solution is to use raw, unprocessed FASTQ files. If that is not possible, Cell Ranger provides an option to computationally trim reads to a uniform length.

  • Re-generate or Use Raw FASTQs: The recommended fix is to work with unaltered data. If your FASTQs were generated with adapter trimming or were manually processed, you should either re-generate them from the original BCL files or locate the original, unprocessed FASTQ files for your analysis.
    • For guidance on the correct settings for Illumina demultiplexing software, please see this article.
  • Trim Reads to a Uniform Length: If you cannot re-generate the FASTQs (e.g., when combining data from different runs), you can instruct Cell Ranger to computationally trim all R1 reads to the shortest length observed in the dataset.
  • Important: The length you trim to must still be equal to or greater than the minimum required R1 length for your assay chemistry (e.g., 28 bp for 3' Gene Expression v3).
  • For cellranger count, use the --r1-length argument.
  • For cellranger multi, use the r1-length parameter in the [libraries] section of your config CSV.
  • You can find more details on this approach in this article.

TXRNGR10010: Error opening FASTQ file: <fastqfilename>

What it means

This error indicates that Cell Ranger cannot access or read one of the FASTQ files you specified. This is almost always due to either an incorrect file path or a file permissions issue.

Solutions

Follow these steps to diagnose and fix the problem.

  • Verify the file path and name. Carefully check the --fastqs path (for cellranger count) or the fastq_id path (in your cellranger multi config CSV) for typos. The best way to confirm that a path is correct is to test it from your command line using the ls command.

For example:

ls /path/to/your/fastqs/sample-name_S1_L001_R1_001.fastq.gz
  • If this command returns an error such as No such file or directory, the path provided to Cell Ranger is incorrect.
  • Check the file permissions. The user running the Cell Ranger pipeline must have read permissions for the FASTQ files themselves, as well as execute permissions for all directories in the path leading to them. You can check the permissions on a file or directory with ls -ld:
ls -ld /path/to/your/fastqs/
ls -l /path/to/your/fastqs/sample-name_S1_L001_R1_001.fastq.gz
  • If you do not have sufficient permissions, you will need to either move the files to a directory you can access or ask a system administrator to adjust the permissions.
  • Check for corrupted or empty files. In rare cases, this error can occur if a FASTQ file is corrupted or empty (0 bytes). Use ls -lh to check the file size and ensure it is not empty. If you suspect a file is corrupt, try re-downloading or re-generating it.

TXRNGR10011: IO error in FASTQ file <filepath>, line: <linenumber>: unexpected end of file.

What it means

A standard FASTQ file contains sequence data in a strict, four-line format for each read:

  • An identifier line starting with @
  • The raw sequence of bases (A, C, G, T, N)
  • A separator line, typically just +
  • A line of ASCII-encoded quality scores, matching the length of the sequence

This error means that while reading a FASTQ file, Cell Ranger reached the end of the file partway through a four-line block. This almost always indicates that the file is incomplete, truncated, or corrupted.

Common Causes

  • Incomplete File Transfer: The most frequent cause. The FASTQ file was not fully copied or downloaded during a transfer from a sequencing core, a public database (like SRA), or during an upload to Cloud Analysis.
  • Failed Demultiplexing: The process that generated the FASTQ file (e.g., mkfastq, bcl2fastq, bcl-convert) may have failed or been terminated prematurely, creating a partial file.
  • Storage or Filesystem Issues: Rarely, a problem with the underlying storage system can lead to file corruption.

Solutions

  • Verify File Integrity: The first step is to confirm that the FASTQ file is truncated. You can do this with a few simple commands. This article provides detailed commands and instructions to test the completeness and integrity of your FASTQ files.
  • Re-acquire the FASTQ Files: Once you have confirmed that a file is incomplete, you must obtain a valid copy before re-running the pipeline. This may involve:
    • Re-downloading the data from its source (e.g., SRA, BaseSpace, Sequence Read Archive).
    • Re-copying the data from its original storage location.
    • Re-running the mkfastq or bcl-convert pipeline if the original demultiplexing process failed.
  • Special Considerations for Cloud Analysis: If you encounter this error on 10x Genomics Cloud Analysis, it strongly suggests an incomplete file upload due to an interrupted network connection.
    • We strongly recommend using the command-line uploader (CLI) for transferring FASTQ files, as it is more robust to network interruptions than the web uploader.
    • This article explains how to be sure your files are properly uploaded to the 10x Cloud. For additional help, please see this article.

TXRNGR10012: Sequence and quality length mismatch: file: __PATH__, line: 16

What it means

In a valid FASTQ file, the sequence of bases (line 2 of a read's record) must have the exact same number of characters as the quality score string (line 4). This error indicates that Cell Ranger has found a read where these lengths do not match.

This is a specific type of file corruption. While the error message is different from TXRNGR10011 ("Unexpected end of FASTQ file"), the underlying causes (e.g., incomplete file transfers, failed demultiplexing) and the solutions are identical.

Solution

Please refer to error TXRNGR10011 to diagnose and resolve this issue. The fundamental problem is a corrupted FASTQ file that must be replaced.

TXRNGR10013: FASTQ headers do not match at line {} of input files

What it means

When processing paired-end sequencing data, Cell Ranger requires that the R1 and R2 FASTQ files are perfectly synchronized. It verifies this by checking that the header line (starting with @) for the Nth read in the R1 file is identical to the header for the Nth read in the R2 file.

This error means the pipeline found a pair of reads that do not have matching headers, indicating the files are out of sync. This is a critical sign of file corruption or an error during file preparation.

Solution

The underlying causes for this error, such as incomplete file transfers or failed demultiplexing, and the required solutions are the same as for other FASTQ integrity errors. Please refer to error TXRNGR10011 to resolve this issue. The files are out of sync and must be replaced with valid, uncorrupted copies.

TXRNGR10014: You declared a library with feature_type = '{feature_type}', but there are no features with that feature_type in the feature reference.

What it means

When you analyze Feature Barcode data, Cell Ranger needs to connect the information in two separate input files:

  • The library CSV (for cellranger count) or multi config CSV (for cellranger multi), which declares your FASTQ files and assigns them a feature_type.
  • The feature reference CSV, which defines the barcode sequences and also assigns them a feature_type.

This error means that a feature_type used in your library/multi config file does not have any corresponding entries in your feature reference. The values in both files must match exactly.

For example, if your cellranger multi config file declares a library like this:

[libraries]
fastq_id,fastqs,feature_types
sample1_fb,./fastqs/,Antibody Capture

Then your feature reference CSV must contain at least one row where the feature_type column is also Antibody Capture:

id,name,read,pattern,sequence,feature_type
CD19,CD19,R2,5PNNNNNNNNNN(BC),GGATCAGAACT,Antibody Capture

Solution

To resolve this, you must ensure the feature_type strings are consistent across your input files.

  • Check for typos. Carefully inspect both your library CSV and your feature reference CSV. The feature_type values are case-sensitive and must match perfectly. A common mistake is using antibody in one file and Antibody Capture in the other.
  • Correct the mismatch. Depending on which file is incorrect, you will need to edit one of them.
    • To understand the correct format for your library CSV, see the documentation for cellranger count here or cellranger multi here.
    • To learn how to properly construct the feature reference CSV for your specific assay, refer to the resources below.
  • Consult Assay-Specific Documentation.
    • General & Antibody Capture: For detailed instructions on creating a feature reference for Antibody Capture (including TotalSeq™-C), see the Feature Reference CSV documentation.
    • BEAM (Antigen Capture): For BEAM assays, you can find the required barcode sequences to build your feature reference on the Antigen Capture analysis page.

TXRNGR10015: The datasets you are trying to aggregate have incompatible MHC alleles for the same control feature id. Please re-run the original multi pipelines with uniform [antigen-specificity] sections.

What it means

A fundamental requirement of the cellranger aggr pipeline is that all input datasets must have been generated using identical reference files. This includes the transcriptome, V(D)J reference, and the feature reference.

This specific error occurs when you are aggregating BEAM (Antigen Capture) datasets and cellranger aggr detects that the [antigen-specificity] section of the feature reference was different between two or more of the input samples.

For example, if the feature reference for sample1 contained this line:

id,mhc_allele,peptide_sequence,feature_name
Control1,HLA-A*02:01,NLVPMVATV,CMV-pp65

But the feature reference for sample2 used a different MHC allele for the same id:

id,mhc_allele,peptide_sequence,feature_name
Control1,HLA-A*03:01,NLVPMVATV,CMV-pp65

The pipeline would fail with this error because the references are not identical.

Solution

To resolve this, you must regenerate your cellranger multi outputs using a single, uniform feature reference for all samples.

  • Create a Uniform Feature Reference. Establish a single, finalized feature reference CSV that will be used for all samples you intend to aggregate. Ensure the [antigen-specificity] section is correct and will be used consistently.
  • Re-run cellranger multi. You must re-run the cellranger multi pipeline for any samples that were originally processed with an incorrect or different version of the feature reference. The goal is to generate outputs for all samples using the exact same references.
  • Re-run cellranger aggr. Once all input datasets (-out.tar.gz files) are compatible and have been generated with the uniform feature reference, you can run the cellranger aggr pipeline again.

TXRNGR10017: You declared a library with library_type = '<library_type>', but there are no features declared with that feature_type in the feature reference.

What it means

When using cellranger count to analyze Feature Barcode data, the pipeline needs to connect information from two separate input files:

  • The libraries CSV, which declares your FASTQ files and assigns them a library_type.
  • The feature reference CSV, which defines the barcode sequences and assigns them a feature_type.

This error indicates that a library_type declared in your libraries CSV does not have any corresponding entries in the feature_type column of your feature reference. The values in both files must match exactly.

For example, if your libraries CSV file declares a library like this:

fastqs,sample,library_type
/path/to/fastqs/,sample1,Antibody Capture

Then your feature reference CSV must contain at least one row where the feature_type column is also Antibody Capture. The pipeline will fail if, for instance, your feature reference only contains a different type:

id,name,read,pattern,sequence,feature_type
MyFeature,MyFeature,R2,5PNNNNNNNNNN(BC),GGATCAGAACT,Custom

Solution

To resolve this, you must ensure the type strings are consistent across your libraries CSV and feature reference files.

  • Check for typos. Carefully inspect both of your CSV files. The library_type from the libraries CSV and the feature_type from the feature reference are case-sensitive and must match perfectly. A common mistake is using antibody in one file and Antibody Capture in the other.
  • Correct the mismatch. Depending on which file is incorrect, you will need to edit one of them.
  • If your feature reference is correct, edit the library_type column in your libraries CSV file to match.
  • If your libraries CSV is correct, edit the feature_type column in your feature reference to match the library_type.

For detailed instructions on constructing these input files, please refer to the cellranger count analysis documentation for the feature reference CSV and the libraries CSV.

TXRNGR10019: The datasets you are trying to aggregate were created with different feature references, but the 'aggr' command requires identical feature references in order to combine datasets.

What it means

A fundamental requirement of the cellranger aggr pipeline is that all input datasets must have been generated using identical reference files. This includes the transcriptome, V(D)J reference, and, for Feature Barcode experiments, the feature reference CSV.

This error is a general check that occurs when cellranger aggr detects that the contents of the feature reference CSV files used to generate the input datasets are not exactly the same. This can be due to any difference, including the number of features, feature IDs, names, or sequences.

For example, if the feature reference for sample1 contained two antibodies:

id,name,read,pattern,sequence,feature_type
CD19,CD19,R2,5PNNNNNNNNNN(BC),GGATCAGAACT,Antibody Capture
CD3,CD3,R2,5PNNNNNNNNNN(BC),GTCTTTGTCAG,Antibody Capture

But the reference for sample2 contained an additional third antibody:

id,name,read,pattern,sequence,feature_type
CD19,CD19,R2,5PNNNNNNNNNN(BC),GGATCAGAACT,Antibody Capture
CD3,CD3,R2,5PNNNNNNNNNN(BC),GTCTTTGTCAG,Antibody Capture
CD4,CD4,R2,5PNNNNNNNNNN(BC),TACTAGCATGC,Antibody Capture

The pipeline would fail with this error because the two feature reference files are not identical.

Solution

To resolve this, you must regenerate your cellranger count or multi outputs using a single, uniform feature reference for all samples.

  • Create a Uniform Feature Reference. Establish a single, finalized feature reference CSV that contains all features used across all samples you intend to aggregate. This will be your "master" reference.
    • You can find detailed instructions for constructing a feature reference on the feature reference CSV documentation page.
  • Re-run cellranger count or multi. You must re-run the cellranger count or cellranger multi pipeline for any samples that were originally processed with a non-uniform feature reference. The goal is to generate outputs for all samples using the exact same set of references.
  • Re-run cellranger aggr. Once all input datasets have been re-processed with the uniform feature reference, you can run the cellranger aggr pipeline again using the new, compatible outputs.

TXRNGR10020: The datasets you are trying to aggregate have incompatible control feature ids. Please re-run the original multi pipelines with uniform [antigen-specificity] sections.

What it means

A fundamental requirement of the cellranger aggr pipeline is that all input datasets must have been generated using identical reference files. This includes the transcriptome, V(D)J reference, and the feature reference.

This specific error occurs when you are aggregating BEAM (Antigen Capture) datasets and cellranger aggr detects that the id for a control feature in the [antigen-specificity] section of the feature reference was different between two or more of the input samples.

For example, if the feature reference for sample1 used the id Control1:

id,mhc_allele,peptide_sequence,feature_name
Control1,HLA-A*02:01,NLVPMVATV,CMV-pp65

But the feature reference for sample2 used the id MyControl for the same feature:

id,mhc_allele,peptide_sequence,feature_name
MyControl,HLA-A*02:01,NLVPMVATV,CMV-pp65

The pipeline would fail with this error because the references are not identical.

Solution

To resolve this, you must regenerate your cellranger multi outputs using a single, uniform feature reference for all samples.

  • Create a Uniform Feature Reference. Establish a single, finalized feature reference CSV that will be used for all samples you intend to aggregate. Ensure the [antigen-specificity] section, including all control feature ids, is identical for all datasets.
  • Re-run cellranger multi. You must re-run the cellranger multi pipeline for any samples that were originally processed with an incorrect or different version of the feature reference. The goal is to generate outputs for all samples using the exact same references.
  • Re-run cellranger aggr. Once all input datasets (-out.tar.gz files) are compatible and have been generated with the uniform feature reference, you can run the cellranger aggr pipeline again.