Troubleshooting¶
Installation and environment¶
| Problem | Cause and fix |
|---|---|
| Environment creation fails | conda update -n base conda, then retry ./PoolSeqFlow install |
nothing provides __glibc >=N |
Your machine's glibc is older than this release's floor of 2.28. ldd --version prints what you have; the floor and why it exists are under The glibc floor. There is no flag for it — use a newer machine |
| Missing dependencies after install | Activate it: conda activate PoolSeqFlow |
| A tool is found but misbehaves | Check whether params.software.* points at a system binary rather than the environment's — version mismatches are not detected |
The run will not start¶
null: command not found¶
Your parameters.config predates the installed version. An absent parameter interpolates as the literal string null, which is why the error names nothing useful and points at a generated script. Rebuild the file — see Upgrading.
Process requirement exceeds available CPUs¶
threads is larger than the machine. Tasks reserve what they really use, so an oversized request fails at submission rather than quietly oversubscribing. Set threads to the cores you have. Resources →
RUN PARAMETER CHECK or METADATA CHANGE CHECK fails¶
Working as designed. An analysis-affecting parameter, or the analysis-affecting part of metadata.csv, differs from what produced your existing outputs. Because completed steps are skipped by looking for output files, continuing would mix results from two configurations in one folder.
The report names what to delete, and how much that is depends on what you changed — a reordered file invalidates less than an edited tag value, and a changed pool size less again. Deleting what it names clears the check. Or PoolSeqFlow reset to discard everything. Why →
PIPELINE VERSION fails¶
These results were produced by a different release. A project belongs to one release, so this one is absolute: nothing else is compared and there is nothing to delete selectively. Either finish the project under the release that started it — every installed version is on your PATH by its own name — or PoolSeqFlow reset and start again under this one. Why →
METADATA CHECK reports a duplicate SampleID¶
A SampleID appears more than once. A row is looked up by it and only the first match is read, so the duplicate would have silently given a sample the wrong read-group tags — producing a valid BAM that nothing downstream could flag. Every problem in the file is reported at once, with line numbers, so fix the whole list before rerunning.
DIRECTORY CHECK fails¶
mainDir and storageDir are the same path, or one of them is the installation. They are two storage tiers and an output moving from one to the other is what marks it finished, which cannot mean anything if they are one place. The installation is a tool that is replaced wholesale on upgrade, so a project inside it would not survive one. Why →
Failures during the run¶
no usable clip range¶
CLIPPING READS <sample>: ERROR: no usable clip range in <file>
CLIPPING READS <sample>: exit 3 = unexpected FastQC header; 4 = no cycle within at_gc_error (0.025)
Exit 4 means no read cycle had A/T and G/C ratios inside at_gc_error. On a GC-skewed genome this is expected, not a fault — raise at_gc_error.
Exit 3 means the FastQC per-base composition table did not have the expected A/T/G/C columns, which points at a FastQC version change or a corrupt report.
Symbolic link errors¶
Confirm you are on Linux. macOS and Windows — including WSL under some filesystem configurations — are not supported. Also check that storageDir is still mounted and was not cleared while the run was in flight.
A step fails and I cannot tell why¶
.nextflow.log names the failing process. Each step also mirrors its own .command.log and .command.err into Logs/<step>/, which is usually more readable.
For a reproducible failure, set threads = 1. That removes concurrency as a variable and makes the logs sequential.
Results are not what I expected¶
Fewer sample columns than samples¶
Rows in metadata.csv sharing an RG_Sample are merged into one VCF column and their depths add together. Eight FASTQ pairs with four distinct RG_Sample values give four columns — usually intentional, occasionally not. The pooling is printed at the start of every run, before any compute. Metadata →
Sample columns in an unexpected order¶
Column order follows metadata.csv row order. Where rows share an RG_Sample, the merged column takes the position of the first of them. Metadata →
REF does not match my reference genome¶
Correct. Step 7 re-encodes each site so the most-read allele across the whole cohort becomes REF, which is what makes frequencies comparable across samples and runs. If you need the assembly's base, take it from the assembly. Why →
A variant I know is real is missing¶
Work outward through the chain — a read lost at alignment cannot be recovered later.
| Check | Parameter |
|---|---|
| Was it filtered at alignment? | cleanBAM.mapq (30 is strict), cleanBAM.filter |
| Was the depth truncated? | That sample's Output/Reports/Depth/ report, then variantCall.maxDepth |
| Was it seen in too few pools? | filterFalsePositives.sampleThreshold — the default discards alleles found in one pool out of eight |
| Below the frequency floor? | poolSize, ploidy |
| Site removed on quality? | vcffilter.minQUAL |
Much less depth than I sequenced for¶
Two usual causes, in order of likelihood:
- MAPQ filtering. At
cleanBAM.mapq = 30, repetitive genomes lose a lot. Compare read counts inOutput/Aligned/andOutput/Ready/. - Duplicate removal. The step 4 log carries
markdup -sstatistics; a high duplicate rate is a library-prep problem, not a pipeline one.
Depth plateaus at one number¶
Something capped it, and the depth report says what. grep -H 'ceiling applied' Output/Reports/Depth/*_depth_report.txt.
If the plateau is in one sample at an unround number, that is its measured ceiling and it is working as intended — the report gives the reason, and param_capMaxDepth overrules it for that sample. If every sample plateaus at the same number, the cap is flat rather than measured: either capBAM.maxDepth is set to a fixed depth, or variantCall.maxDepth is non-zero. Depth capping →
Genotype-based tools find nothing in my VCFs¶
FORMAT/GT is set to ./. throughout, deliberately — a pool has no genotype, and leaving bcftools' diploid call in place would invite tools to read it as one. Use AD and DP.
Annotated VCF contains sites missing from my frequency tables¶
Step 8 runs on step 6's output, in parallel with the frequency branch, so it never sees the step 7 filters. Its allele encoding is also the original reference-based one, not the major-allele normalized one. Join on CHROM/POS and expect unmatched rows. Details →
Resume behavior¶
A re-run skips too many steps¶
Steps skip themselves when their outputs already exist. Delete the stale outputs, or PoolSeqFlow reset to start over.
A re-run submits every job anyway¶
Expected. Step-skipping happens inside each task rather than before it, so a fully resumed run still submits roughly one short job per process per sample. Resume Logic →
-resume appears to do nothing¶
Correct — PoolSeqFlow does not use Nextflow's -resume, and the wrapper never passes it. PoolSeqFlow run already resumes. Resume Logic →
A step reruns after an interrupted job¶
If the interruption hit a cross-filesystem move, the partial copy was left under a temporary name rather than under the final one, so the step correctly runs again. That is the atomic move working.
An analysis module¶
A module stops on a C++ compile¶
basicstats computes its per-site work through a compiled function by default, and stops rather than falling back if it cannot build one. The commonest cause is calling Rscript yourself instead of going through PoolSeqFlow analysis, which activates the environment the compiler lives in; the next commonest is /tmp mounted noexec. Add nocpp to finish now — the numbers are identical — and see When the compiled path will not build for the full list.
doFuture is not installed¶
The module was asked for more than one worker and cannot go parallel. Either install it into the analysis environment, or set analysis.modules.basicstats.workers = 1. It does not quietly run on one worker instead: a run that took a different path than the one you asked for is a run whose timings mean nothing.
A pool holds one chromosome¶
Refused, and it is the only pool size that is. A single haploid genome has no segregating sites, and the correction every diversity estimate applies divides by n_eff - 1, which is zero there. Correct ploidy, or that pool's param_poolSize. →
Getting help¶
Include the failing step, the relevant Logs/ excerpt and your parameters.config with paths redacted when opening an issue: github.com/ozankiratli/PoolSeqFlow/issues