Troubleshooting

This page lists common LENS runtime issues and practical fixes.

Path value cannot be empty

Error example:

ERROR ~ Error executing process > '...:combine_nt_fastas (...)'
Caused by:
  Path value cannot be empty

Typical cause:

  • A join/fallback path emitted an empty value into a process input declared as path(...).

Recommended checks:

  • Inspect upstream join outputs for the failing sample key in .nextflow.log.

  • Confirm fallback placeholders use a real file path (for example, a configured dummy file) rather than an empty list/value.

toIndex = 6 (tuple shape mismatch)

Error example:

ERROR ~ toIndex = 6

Typical cause:

  • A downstream map/slice operation (e.g. it[6..-1]) is receiving a shorter tuple than expected due to inconsistent join output shape.

Recommended checks:

  • Print/debug tuple shapes around the failing join.

  • Ensure fallback/no-match records preserve the same tuple structure as matched records for each workflow stage.

Unexpected duplicate process runs per sample key

Symptom example:

  • combine_peptide_fastas runs twice for the same [Patient_Name, Run_Name, Dataset] key.

Typical cause:

  • A subjoin emits both joined and no_matches for the same key, and downstream logic concatenates both channels.

Recommended checks:

  • Verify no-match outputs are key-exclusive from joined outputs.

  • Enforce key-level exclusivity in join logic before channel concatenation.

Unable to resume cached task

Warning example:

WARN: [process (...)] Unable to resume cached task -- See log file for details

Typical causes:

  • Process script/body changed.

  • Input channel content/ordering changed.

  • Container/image, process directives, or relevant params changed.

Recommended checks:

  • Confirm whether code or parameter changes are expected.

  • Re-run with -resume first; if instability persists, run clean for the affected step(s).

Manifest/sample pairing issues

Symptoms:

  • Missing expected DNA/RNA pairings.

  • No outputs from downstream variant or antigen workflows.

Typical causes:

  • Inconsistent Run_Name prefixes (ad-, nd-, ar-, nr-).

  • Misaligned Patient_Name/Dataset values.

  • Grouping mismatches when using Group for multi-timepoint RNA.

Recommended checks:

  • Run raft.py check-manifest -m <MANIFEST>.

  • Validate prefixes and group assignments for each patient/sample set.

Reference/config mismatches

Symptoms:

  • Tool failures early in alignment/annotation/phasing.

  • Missing indices, incompatible GTF/FASTA combinations, or annotation errors.

Recommended checks:

  • Confirm all expected references are present under references/.

  • Ensure reference versions are compatible (e.g. hg38 + matching GTF/annotation).

  • Verify relevant params.lens$... reference paths in main.nf or config.