Repository navigation
Troubleshooting
When a run fails for a common reason, N-WAVE says so in plain language: in the error notice, the run panel and the run's entry under History, with the step it happened in (Show moves the canvas to it) and a link to the matching section below. The full output is under the run panel's Log tab. For the words used here, see the glossary on the Help page in N-WAVE (home page → Help).
On this page: Run failures · Installation and Docker · Files and paths · Clusters · The browser demo · Saving
When N-WAVE recognises why a run failed, it says so above the run's log, with the log lines it went by and how sure it is (how N-WAVE explains things). The sections below say what to do.
The step used more memory than it was given and was killed (exit status 137). Raise Maximum Memory in Global Settings → Run limits (and in the workflow's Execution Settings → Resources if it has lower limits of its own), or the step's memory in its panel. On Docker Desktop, also give Docker more memory (Settings → Resources).
Nextflow stopped a step that was still running when it reached its time limit
(Process exceeded running time limit; Nextflow 26.04 may say process hasn't exited
instead). nf-core test profiles give every step at most 1 hour. Steps take longer with less
memory or fewer CPUs than the pipeline expects, or when the run's files are on a slow drive
(on Windows, a folder of the Windows drive shared into Docker is much slower than Docker's
own disk). Raise Maximum Memory and Maximum CPU Cores, then run again with
Resume so finished steps are reused. N-WAVE lets every step run as long as the run's own
time limit (Execution Timeout), which replaces the test profile's 1 hour.
A step asked for more CPUs or memory than the run may use, or the run reached its time
limit. The run's first lines say which limits it got. Raise them in Global Settings → Run limits,
and in the workflow's Execution Settings → Resources if it has lower limits of its own. The server caps them with NWAVE_MAX_CPUS,
NWAVE_MAX_MEMORY and NWAVE_EXECUTION_TIMEOUT (24 hours by default; see
Configuration).
The step runs in a container, but Docker isn't running or N-WAVE can't reach it. Start Docker (Docker Desktop on Windows and macOS) and wait until it says it's running. Check again in the workflow check (next to the Run button) shows when N-WAVE can reach it.
Docker couldn't download the step's image: the name or tag is wrong, the image doesn't exist,
or the registry can't be reached from this computer's network or proxy. Check a custom
process's image, and that this computer can reach quay.io, community.wave.seqera.io and
docker.io (nf-core steps use the first two).
The step runs a program that isn't installed where it ran (exit status 127). Without Docker, the program isn't installed on the computer: turn on Docker in Execution Settings → Execution. In a container, the image doesn't have it: give a custom process an image that does. Also check the command for typos.
The disk the run writes to is full. Delete old runs from results/, clear workflows'
run caches (Execution Settings → Run cache) and remove unused Docker images
(docker system prune). On Docker Desktop, raise the disk size (Settings → Resources).
An input given as an address (https://…) couldn't be downloaded: the address is wrong, or
it can't be reached from this computer. Open it in a browser, check the network or proxy, or
upload the file instead.
On a pipeline's first run, Nextflow downloads it from GitHub. "Forbidden -- Provide your
GitHub user name and password" usually means GitHub's limit for downloads without an account
(60 an hour) is used up, or a firewall blocks github.com and api.github.com. Wait an hour,
or give the N-WAVE server a GitHub access token in the GITHUB_TOKEN environment variable
(any token works, it needs no permissions); Nextflow then uses your account's limit.
nf-core pipelines need Nextflow plugins (such as nf-schema), which Nextflow downloads from
registry.nextflow.io on their first use. When it can't reach it, Nextflow 25.10 stops with
the puzzling ERROR ~ Conversion = '4' (older versions say a plugin can't be found). Allow
that address in the firewall or proxy of the computer running Nextflow, then run again.
A file the workflow reads isn't where it looks. Upload it to a File Input node, and check that the names in samplesheets and parameters match the uploaded files exactly.
The step finished but didn't write a file it declares as output. For a custom process, check
that its script writes exactly the file names in its output: block.
The first run downloads Nextflow (the nextflow/nextflow image), then each step's container
image, and for a pipeline the pipeline itself. That can take many minutes and several GB.
Later runs reuse the downloads. Fix a failed run and use Resume to skip the steps that
already finished (Running workflows).
Docker Desktop gives its containers a fixed amount of memory, often 2 to 8 GB. Steps that need more fail with Out of memory even if the computer has more. Raise it in Settings → Resources → Memory and restart Docker Desktop. The examples need 8 GB; aligning reads to a human or mouse genome needs about 40 GB.
N-WAVE itself runs natively. Many Nextflow images exist only for Intel/AMD, so the runner
uses that platform by default and Docker emulates it, which is slower. If your Nextflow
version has an ARM image, set NEXTFLOW_PLATFORM=native on the backend.
Docker Engine 29 and newer refuse the old Docker client in the Nextflow images. N-WAVE
handles this itself; if it still happens, set DOCKER_API_VERSION on the backend to the
version docker version reports as the server's minimum API version.
Check that the containers run (docker compose -f latest.yml ps), that nothing else uses
port 5173 or 5001, and that you open the address N-WAVE allows (CORS_ORIGIN, see
Installation).
Nextflow doesn't run on Windows itself; use the
Docker installation (Docker Desktop
with WSL 2). There, Nextflow only sees the results folder:
- Keep Execution Settings → Output → Output Directory at
resultsor a folder inside it. A Windows path such asC:\datacan't be used. - Give inputs as uploaded files or URLs, not as
C:\…paths in samplesheets or parameters. - Write paths with forward slashes (
results/run1), also on Windows.
Files up to 256 KB are saved with the workflow. Larger files stay in the browser tab only, so after a reload the workflow check asks you to upload them again. A file can be up to 36 MB, and one run's uploads may total about 37 MB; for larger data, use URLs (or absolute paths where Nextflow runs on the computer itself) in a Samplesheet or Parameters node.
The jobs ask for more than the partition allows, usually more time per step than its limit
(squeue shows PartitionTimeLimit). Lower Time per step in the run profile or choose
another partition. See Run profiles.
N-WAVE can only submit jobs when its backend runs Nextflow on a machine that has sbatch.
The Docker installation can't; export the project and run it on the cluster instead
(Exporting projects).
The browser demo has no server: it can't run workflows, and it keeps your workflows, custom nodes and installed nf-core modules in this browser only (clearing site data removes them). Export a project to run it elsewhere, or install N-WAVE.
The workflow was saved in another tab, or changed by a custom node update, after you opened it here. Nothing was overwritten. Pick Load the saved version to drop your changes here, Keep mine as a copy to save yours as a new workflow, or Replace it with mine. See Building workflows.
Search the issues or open one with how you run N-WAVE, the steps to reproduce and the run's log.