Troubleshooting
===============

This page lists common LENS runtime issues and practical fixes.

Path value cannot be empty
--------------------------

Error example:

.. code-block:: console

  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:

.. code-block:: console

  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:

.. code-block:: console

  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.