Skill Tracer
Skills › Knowledge Work Plugins › nextflow-development › troubleshooting.md

troubleshooting.md

137 lines · bio-research/skills/nextflow-development/references/troubleshooting.md at 2574e29

Open on GitHub
1# Troubleshooting
2
3Quick fixes for common nf-core pipeline issues.
4

Troubleshooting

Quick fixes for common nf-core pipeline issues.

Raw lines 1 to 4
5## Contents
6- [Exit Codes](#exit-codes)
7- [HPC/Singularity Issues](#hpcsingularity-issues)
8- [Pipeline Failures](#pipeline-failures)
9- [RNA-seq Specific](#rna-seq-specific)
10- [Sarek Specific](#sarek-specific)
11- [ATAC-seq Specific](#atac-seq-specific)
12- [Resource Management](#resource-management)
13- [Getting Help](#getting-help)

Contents

  • Exit Codes
  • HPC/Singularity Issues
  • Pipeline Failures
  • RNA-seq Specific
  • Sarek Specific
  • ATAC-seq Specific
  • Resource Management
  • Getting Help
Raw lines 5 to 14
15## Exit Codes
17Common exit codes indicating resource issues (per [nf-core docs](https://nf-co.re/docs/usage/troubleshooting/crash_halfway)):
19| Code | Cause | Fix |
20|------|-------|-----|
21| 137 | Out of memory | `--max_memory '32.GB'` or `'64.GB'` for WGS |
22| 143 | Out of memory | `--max_memory '32.GB'` or `'64.GB'` for WGS |
23| 104, 134, 139, 247 | Out of memory | Increase `--max_memory` |
24| 1 | General error | Check `.nextflow.log` for details |
26Most pipelines auto-retry with 2x then 3x resources before failing.

Exit Codes

Common exit codes indicating resource issues (per nf-core docs):

CodeCauseFix
137Out of memory--max_memory '32.GB' or '64.GB' for WGS
143Out of memory--max_memory '32.GB' or '64.GB' for WGS
104, 134, 139, 247Out of memoryIncrease --max_memory
1General errorCheck .nextflow.log for details

Most pipelines auto-retry with 2x then 3x resources before failing.

Raw lines 15 to 27
28## HPC/Singularity Issues

HPC/Singularity Issues

Raw lines 28 to 29
30### Singularity cache issues
31```bash
32export NXF_SINGULARITY_CACHEDIR="$HOME/.singularity/cache"
33mkdir -p $NXF_SINGULARITY_CACHEDIR
34```

Singularity cache issues

export NXF_SINGULARITY_CACHEDIR="$HOME/.singularity/cache"
mkdir -p $NXF_SINGULARITY_CACHEDIR
Raw lines 30 to 35
36### Using Singularity instead of Docker
37On HPC systems without Docker, use Singularity:
38```bash
39nextflow run nf-core/<pipeline> -profile singularity ...
40```
42> **Note**: For basic environment setup (Docker, Nextflow, Java installation), see the inline instructions in Step 1 of SKILL.md.

Using Singularity instead of Docker

On HPC systems without Docker, use Singularity:

nextflow run nf-core/<pipeline> -profile singularity ...
Note: For basic environment setup (Docker, Nextflow, Java installation), see the inline instructions in Step 1 of SKILL.md.
Raw lines 36 to 43
44## Pipeline Failures

Pipeline Failures

Raw lines 44 to 45
46### Container pull failed
47- Check network connectivity
48- Try: `-profile singularity` instead of docker
49- For offline: `nf-core download <pipeline> -r <version>`

Container pull failed

  • Check network connectivity
  • Try: -profile singularity instead of docker
  • For offline: nf-core download <pipeline> -r <version>
Raw lines 46 to 50
51### "No such file" errors
52- Use **absolute paths** in samplesheet
53- Verify files exist: `ls /path/to/file`

"No such file" errors

  • Use absolute paths in samplesheet
  • Verify files exist: ls /path/to/file
Raw lines 51 to 54
55### Resume not working
56```bash
57# Check work directory exists
58ls -la work/
60# Force clean restart (loses cache)
61rm -rf work/ .nextflow*
62nextflow run nf-core/<pipeline> ...
63```

Resume not working

# Check work directory exists
ls -la work/

# Force clean restart (loses cache)
rm -rf work/ .nextflow*
nextflow run nf-core/<pipeline> ...
Raw lines 55 to 64
65## RNA-seq Specific

RNA-seq Specific

Raw lines 65 to 66
67### STAR index fails
68- Increase memory: `--max_memory '64.GB'`
69- Or provide pre-built: `--star_index /path/to/star/`

STAR index fails

  • Increase memory: --max_memory '64.GB'
  • Or provide pre-built: --star_index /path/to/star/
Raw lines 67 to 70
71### Low alignment rate
72- Verify genome matches species
73- Check FastQC for adapter contamination
74- Try different aligner: `--aligner hisat2`

Low alignment rate

  • Verify genome matches species
  • Check FastQC for adapter contamination
  • Try different aligner: --aligner hisat2
Raw lines 71 to 75
76### Strandedness detection fails
77- Specify explicitly: `--strandedness reverse`
78- Common values: `forward`, `reverse`, `unstranded`

Strandedness detection fails

  • Specify explicitly: --strandedness reverse
  • Common values: forward, reverse, unstranded
Raw lines 76 to 79
80## Sarek Specific

Sarek Specific

Raw lines 80 to 81
82### BQSR fails
83- Check known sites for genome
84- Skip for non-standard references: `--skip_bqsr`

BQSR fails

  • Check known sites for genome
  • Skip for non-standard references: --skip_bqsr
Raw lines 82 to 85
86### Mutect2 no variants
87- Verify tumor/normal pairing
88- Check samplesheet `status` column: 0=normal, 1=tumor

Mutect2 no variants

  • Verify tumor/normal pairing
  • Check samplesheet status column: 0=normal, 1=tumor
Raw lines 86 to 89
90### Out of memory for WGS
91```bash
92--max_memory '128.GB' --max_cpus 16
93```

Out of memory for WGS

--max_memory '128.GB' --max_cpus 16
Raw lines 90 to 94
95### DeepVariant GPU issues
96- Ensure NVIDIA Docker runtime configured
97- Or use CPU mode (slower)

DeepVariant GPU issues

  • Ensure NVIDIA Docker runtime configured
  • Or use CPU mode (slower)
Raw lines 95 to 98
99## ATAC-seq Specific

ATAC-seq Specific

Raw lines 99 to 100
101### Low FRiP score
102- Check library complexity in `plotFingerprint/`
103- May indicate over-transposition

Low FRiP score

  • Check library complexity in plotFingerprint/
  • May indicate over-transposition
Raw lines 101 to 104
105### Few peaks called
106- Lower threshold: `--macs_qvalue 0.1`
107- Use broad peaks: `--narrow_peak false`

Few peaks called

  • Lower threshold: --macs_qvalue 0.1
  • Use broad peaks: --narrow_peak false
Raw lines 105 to 108
109### High duplicates
110- Normal for low-input samples
111- Pipeline removes by default
112- Consider deeper sequencing

High duplicates

  • Normal for low-input samples
  • Pipeline removes by default
  • Consider deeper sequencing
Raw lines 109 to 113
114## Resource Management

Resource Management

Raw lines 114 to 115
116### Set resource limits
117```bash
118--max_cpus 8 --max_memory '32.GB' --max_time '24.h'
119```

Set resource limits

--max_cpus 8 --max_memory '32.GB' --max_time '24.h'
Raw lines 116 to 120
121### Check available resources
122```bash
123# CPUs
124nproc
126# Memory
127free -h
129# Disk
130df -h .
131```

Check available resources

# CPUs
nproc

# Memory
free -h

# Disk
df -h .
Raw lines 121 to 132
133## Getting Help
1351. Check `.nextflow.log` for error details
1362. Search nf-core Slack: https://nf-co.re/join
1373. Open issue on GitHub: https://github.com/nf-core/<pipeline>/issues

Getting Help

  1. Check .nextflow.log for error details
  2. Search nf-core Slack: https://nf-co.re/join
  3. Open issue on GitHub: https://github.com/nf-core/<pipeline>/issues
Raw lines 133 to 137