spaceranger mkfastq or
spaceranger count pipelines fail, they automatically generate a "debug tarball" that contains the logs and metadata generated by the pipestance leading up to failure. This file, named
sample_id.mri.tgz, can be e-mailed to [email protected] to help resolve any issues with using Space Ranger.
You can also use the
spaceranger upload command to send the tarball to 10x Genomics. Customize the code below with your email and
spaceranger upload [email protected] sample_id.mri.tgz
Preflight failures are the most common and are the result of invalid input data or runtime parameters. Because they occur before the pipeline actually runs, there is no pipeline output and the error is reported directly to your terminal.
Common preflight failures include failing to install bcl2fastq.
spaceranger mkfastq generates the following error if Illumina's bcl2fastq software is not installed:
[error] On machine: workstation.university.edu, bcl2fastq or configureBclToFastq.pl not found on PATH.
In-flight failures are generally the result of factors external to the pipeline such as running out of system memory or disk space. Different stages may fail in different ways so the specific error messages vary widely.
Finding relevant error logs
There are a few important files that are saved to your pipeline output directory which, by default, is named according to the flowcell serial number for
spaceranger mkfastq (e.g.,
HAWT7ADXX) and your
--id name for
- The pipeline execution log that is output to your terminal during pipeline execution is also saved to
- Stages that experience a hard failure generate an
_errorsfile containing the precise error that caused a stage to halt. You view these error logs, if they exist, using
find output_dir -name _errors | xargs cat
- Each stage also logs its stdout and stderr streams to
_stdoutfiles. These logs can be listed using
find output_dir -name _stderrand may contain elucidating error messages in stages that execute third-party applications such as STAR.
A more detailed description of the pipeline output directory and its contents is given in the [Pipestance Structure] page.
Resuming a failed pipestance
Once you have determined the reason for failure and are ready to continue running the pipeline, you can typically issue the same
spaceranger command to continue execution of the pipestance from the stage that originally failed.
spaceranger mkfastq or
spaceranger count, it detects if its intended output directory already exists. If it does, this existing pipeline output directory is treated as an incomplete pipestance and resumes execution. This feature allows pipelines to be stopped and resumed with great flexibility, but it can also result in errors such as:
RuntimeError: /home/jdoe/runs/sample345 is not a pipestance directory
which indicates that you specified a
--id that corresponds to an existing directory that was not created by Space Ranger.
The following error:
RuntimeError: pipestance 'HAWT7ADXX' already exists and is locked by another Martian instance. If you are sure no other Martian instance is running, delete the _lock file in /home/jdoe/runs/HAWT7ADXX and start Martian again.
indicates that you may already have a copy of
spaceranger running that is using the same output directory. If you are sure that there is no pipestance running in the given output directory, you can either remove that output directory entirely (
mv HAWT7ADXX HAWT7ADXX.old) to restart the pipestance from the beginning, or you can remove the pipestance's lock file (
rm HAWT7ADXX/_lock) and re-run the
spaceranger command to resume pipeline execution.
If you encounter the following error when attempting to resume a pipestance:
RuntimeError: pipestance 'sample345' already exists with different invocation file /home/jdoe/runs/sample345/_invocation
you are attempting to resume a pipestance using command-line arguments that are different from those used to first run it. You can view the parameters input to the existing pipeline by examining the
_log file located in the output directory (e.g.,
head -n20 /home/jdoe/runs/sample345/_log)
Alerts are generally the result of factors inherent in library preparation and sequencing instead of software. Abnormal data (including common short-read sequencing metrics and Visium-specific statistics) are raised in the form of alerts that are printed in the output
web_summary.html file. Alerts do not affect the operation of the pipeline, but they do highlight potential causes for abnormal or missing data.
Alerts come in two severity levels:
WARNalerts indicate that some parameter is suboptimal, but there may still be useful data in the pipeline output.
ERRORalerts indicate a major issue, and there is unlikely to usable results in the output.
For example, running
spaceranger where the sequencing quality is low will show a warning like this:
WARN alerts are not always indicative of a lost sequencing run. Generally re-running
spaceranger count with the proper human reference would likely not return this alert. For FFPE samples with R2 length > 50 bp run with Space Ranger versions prior to 2.0, re-running
spaceranger count with
--r2-length=50 will most likely address this alert, as longer R2 length can lead to artificially lowered base qualities due to sequencing into the polyA homopolymer region of the probe.
There are also image related warnings:
Alignment failure often manifests as a subtle rotation or translation that misplaces spots by a fraction of the spot diameter. These failures are difficult to automatically catch, as detection of the alignment failure is similar to the process of alignment itself. However, if the alignment process reports a scaling, rotation, or translation of the input image that seems truly implausible, the pipeline will issue a warning that the user should closely inspect the results of the fiducial alignment in the Image panel. It is highly recommended that the user always inspects the quality-control images from the pipeline for subtle errors, even in absence of such a warning.
Poorly constructed libraries typically display more severe
ERROR alerts. For example, a low-quality library may result in the following alerts:
The presence of these
ERROR alerts indicate that results from this pipestance are likely dubious.