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

This page maps common RAFT symptoms to the first command or file to check.
Most commands should be run from the RAFT workspace root, the directory that
contains ``.raft.cfg``.

.. raw:: html

   <style>
     p.rubric {
       font-size: 1.15em;
       font-weight: 700;
       color: #111827;
       border-left: 4px solid #2563eb;
       padding: 0.5rem 0 0.5rem 0.75rem;
       margin-top: 1.75rem;
       margin-bottom: 0.75rem;
       background: #eff6ff;
       border-radius: 0 4px 4px 0;
     }
   </style>

.. rubric:: Where should I run RAFT commands?

Run RAFT from the workspace root created by:

.. code-block:: console

  $ raft setup --default

That directory contains ``.raft.cfg`` and usually has subdirectories such as
``projects/``, ``inputs/``, ``references/``, and ``shared/``.

If a command fails with a missing ``.raft.cfg`` error, change back to the
workspace root and rerun it:

.. code-block:: console

  $ cd /path/to/raft-workspace
  $ raft project-status --project-id my-project

.. rubric:: How do I check project status?

Start with the read-only project summary:

.. code-block:: console

  $ raft project-status --project-id my-project

Use this before rerunning a project. It reports detected workflow context,
manifest information, latest trace status, reportable outputs, and suggested
next commands.

If another tool needs the information:

.. code-block:: console

  $ raft project-status --project-id my-project --json

.. rubric:: Why are there no reports after a setup-only run?

This is expected. ``--setup-only`` creates or updates project files and loads
modules, but it does not launch Nextflow.

Check project state:

.. code-block:: console

  $ raft project-status --project-id my-project

Run the prepared project:

.. code-block:: console

  $ raft run --project-id my-project

After the workflow has run, launch the viewer:

.. code-block:: console

  $ raft generate-reports --project-id my-project

.. rubric:: Why can't RAFT find my manifest?

``raft check-manifest`` accepts:

- an absolute path
- a path relative to the current workspace
- a filename or path under the configured RAFT metadata directory

Examples:

.. code-block:: console

  $ raft check-manifest --manifest my_manifest.tsv
  $ raft check-manifest --manifest projects/my-project/inputs/metadata/my_manifest.tsv
  $ raft check-manifest --manifest /abs/path/to/my_manifest.tsv

If several files have the same name, use a more specific path.

If the workflow has a manifest UI template, pass it explicitly when needed:

.. code-block:: console

  $ raft check-manifest \
      --manifest my_manifest.tsv \
      --manifest-ui-template path/to/workflow.manifest-ui.json

.. rubric:: How do I create a manifest?

For a new project, ``--manifest`` is optional. If you omit it, RAFT opens the
manifest generator:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --setup-only

For command-line work, create a starter TSV:

.. code-block:: console

  $ raft manifest-template --output my_manifest.tsv

Use a workflow-owned manifest template when available:

.. code-block:: console

  $ raft manifest-template \
      --manifest-ui-template path/to/workflow.manifest-ui.json \
      --output my_manifest.tsv

.. rubric:: What does the missing Nextflow profile warning mean?

RAFT can continue with conservative local resource caps when no default
Nextflow profile is configured. For a real cluster or production run, provide a
profile explicitly:

.. code-block:: console

  $ raft run --project-id my-project --profile slurm

If you are still setting up a project, use ``--setup-only`` first:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --setup-only

``--setup-only`` does not need a Nextflow execution profile because it does not
launch Nextflow.

.. rubric:: My workflow failed. What do I check first?

Start with:

.. code-block:: console

  $ raft project-status --project-id my-project

Then inspect the latest trace and log files reported by project status. Common
locations are:

- ``projects/my-project/outputs/reports/trace-*.txt``
- ``projects/my-project/logs/.nextflow.log``
- task work directories printed by Nextflow

After fixing the cause, rerun:

.. code-block:: console

  $ raft run --project-id my-project

.. rubric:: How do I list available workflow steps?

After project setup, list steps from a loaded module:

.. code-block:: console

  $ raft list-steps --project-id my-project --module lenstools

Show one step:

.. code-block:: console

  $ raft list-steps \
      --project-id my-project \
      --module lenstools \
      --step lenstools_score_review_candidates

Use JSON for automation:

.. code-block:: console

  $ raft list-steps --project-id my-project --module lenstools --json

.. rubric:: Why aren't files preloading in the report viewer?

``raft generate-reports`` launches a local viewer/server. It may keep the
terminal occupied while the viewer is running.

Launch with project outputs:

.. code-block:: console

  $ raft generate-reports --project-id my-project

Launch the viewer without preloading files:

.. code-block:: console

  $ raft generate-reports --project-id my-project --no-load

Try synthetic data without a project:

.. code-block:: console

  $ raft generate-reports --demo

If no files are preloaded, check whether the workflow has actually run and
whether the workflow report configuration points to the report directories that
the workflow creates:

.. code-block:: console

  $ raft project-status --project-id my-project

.. rubric:: Can I skip downloads during setup?

Use ``--setup-only`` with ``--skip-downloads``:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --setup-only \
      --skip-downloads

For deeper setup debugging, ``skip_downloads`` is also available through
``--debug``:

.. code-block:: console

  $ raft run-ots \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --setup-only \
      --debug skip_downloads

Related pages
-------------

- :doc:`which-command`
- :doc:`running-raft-locally`
- :doc:`project-status`
- :doc:`manifest`
- :doc:`ui`