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.

Where should I run RAFT commands?

Run RAFT from the workspace root created by:

$ 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:

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

How do I check project status?

Start with the read-only project summary:

$ 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:

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

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:

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

Run the prepared project:

$ raft run --project-id my-project

After the workflow has run, launch the viewer:

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

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:

$ 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:

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

How do I create a manifest?

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

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

For command-line work, create a starter TSV:

$ raft manifest-template --output my_manifest.tsv

Use a workflow-owned manifest template when available:

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

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:

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

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

$ 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.

My workflow failed. What do I check first?

Start with:

$ 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:

$ raft run --project-id my-project

How do I list available workflow steps?

After project setup, list steps from a loaded module:

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

Show one step:

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

Use JSON for automation:

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

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:

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

Launch the viewer without preloading files:

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

Try synthetic data without a project:

$ 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:

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

Can I skip downloads during setup?

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

$ 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:

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