Why did my Dry Lab / Computational fail?
Job killed by the scheduler or OS for exceeding allocated memory. The job terminated with a non-zero exit status. A large fraction of reads fail to align to the reference. A package resolved to a version incompatible with the pipeline.
Playbooks
- Dry Lab / Computational: out of memory (oom)Job killed by the scheduler or OS for exceeding allocated memory.
- Dry Lab / Computational: exit code failureThe job terminated with a non-zero exit status.
- Dry Lab / Computational: low alignment / mapping rateA large fraction of reads fail to align to the reference.
- Dry Lab / Computational: unpinned dependency errorA package resolved to a version incompatible with the pipeline.
FAQ — Dry Lab / Computational
- Out of memory (OOM)
- Job killed by the scheduler or OS for exceeding allocated memory. Increase the Slurm memory flag (e.g. --mem=32G → --mem=64G) — The single fastest fix when the job is simply under-provisioned. Reduce batch size and re-run — Lowers peak memory per iteration at the cost of some throughput. Verify input file sizes against the protocol's expected dataset — Catches a wrong or unfiltered material input before more memory is requested. Reduce thread/worker count so fewer dataset copies are held in memory simultaneously — Trades wall-clock time for memory headroom.
- Exit code failure
- The job terminated with a non-zero exit status. Re-check the input dataset path for typos or a stale symlink — The most common single cause of an immediate non-zero exit. Read the full CLI log / stack trace and fix the reported line — Exit-code failures almost always log the true cause; do not guess before reading it. Pin the environment/container to the exact version specified in the protocol — Version drift between runs is the second most common cause. Verify the size/checksum of every upstream input file before re-running — Catches a silently truncated upstream step.
- Low alignment / mapping rate
- A large fraction of reads fail to align to the reference. Confirm the reference build matches the organism and annotation version used elsewhere in the pipeline — A stale or mismatched index is the most common systemic cause. Run adapter/quality trimming (e.g. Trim Galore, fastp) before re-aligning — Untrimmed adapters directly reduce mapping rate. BLAST a sample of unmapped reads to check for species/contamination mismatch — Confirms whether the sample itself, not the pipeline, is the issue. Relax aligner mismatch/seed parameters for shorter or noisier reads — Fixes rate for legitimately lower-quality but on-target reads.
- Unpinned dependency error
- A package resolved to a version incompatible with the pipeline. Pin every direct dependency to an exact version (==x.y.z) in the environment spec — Eliminates the whole class of drift-on-rebuild failures. Generate and commit a full lockfile (pip freeze / conda-lock) alongside the top-level spec — Pins transitive dependencies too, not just direct ones. Re-build the environment from the lockfile in a clean container and re-run — Confirms the pin actually reproduces the original working state. Record the exact container/conda build hash in the run's execution log — Makes the next failure immediately diagnosable without re-deriving it.