Common Errors¶

Solutions for frequently encountered errors in the aa-tRNA-seq pipeline.

POD5 File Errors¶

No POD5 Files Found¶

Error:

1

Error: No input files found for sample: sample1

Causes:

1. Incorrect path in samples file
2. POD5 files not in expected subdirectories
3. Wrong file extension

Solutions:

1. Verify the path exists:

   Bash
   1	ls -la /path/from/samples/file/

2. Check for POD5 files in expected locations:

   Bash
   1 2 3	ls /path/to/run/pod5_pass/ ls /path/to/run/pod5_fail/ ls /path/to/run/pod5/

3. Ensure files have .pod5 extension (not .fast5)

POD5 Merge Fails¶

Error:

1

pod5 merge: error

Solutions:

1. Check disk space:

   Bash
   1	df -h .

2. Verify POD5 files are valid:

   Bash
   1	pod5 inspect summary input.pod5

3. Check for corrupted files and exclude them

GPU Errors¶

CUDA Out of Memory¶

Error:

1

RuntimeError: CUDA out of memory

Solutions:

1. Ensure exclusive GPU access in cluster profile:

   YAML
   1 2	set-resources: - rebasecall:lsf_extra="-gpu num=1:j_exclusive=yes"

2. Reduce concurrent GPU jobs:

   YAML
   1 2	resources: - ngpu=4

3. Check for other GPU processes:

   Bash
   1	nvidia-smi

No CUDA GPUs Available¶

Error:

1

No CUDA GPUs are available

Solutions:

1. Verify CUDA installation:

   Bash
   1	nvidia-smi

2. Check CUDA_VISIBLE_DEVICES:

   Bash
   1	echo $CUDA_VISIBLE_DEVICES

3. Verify job is running on GPU node (for cluster execution)

GPU Driver Mismatch¶

Error:

1

CUDA driver version is insufficient for CUDA runtime version

Solutions:

1. Check driver version:

   Bash
   1	nvidia-smi | head -3

2. Update GPU drivers (contact system admin)

3. Use a compatible Dorado version

Memory Errors¶

Out of Memory¶

Error:

1
2
3

MemoryError
# or
Killed (signal 9)

Solutions:

1. Increase memory for the rule in cluster profile:

   YAML
   1 2	set-resources: - failing_rule:mem_mb=64

2. For local execution, close other applications

3. Check system memory:

   Bash
   1	free -h

Modkit Memory Issues¶

Error:

1

modkit extract calls: memory allocation failed

Solution:

The modkit_extract_calls rule requires significant memory (default 96 GB):

1
2

set-resources:
  - modkit_extract_calls:mem_mb=128

Alignment Errors¶

BWA Index Missing¶

Error:

1

[bwa_idx_load_from_disk] fail to locate the index

Solution:

The index should be built automatically. If it fails, build manually:

1

bwa index resources/ref/sacCer3-mature-tRNAs-dual-adapt-v2.fa

No Reads Aligned¶

Error:

1

Warning: 0 reads aligned

Causes:

1. Wrong reference sequence
2. Incompatible read format
3. Data quality issues

Solutions:

1. Verify reference matches your samples
2. Check FASTQ quality:

   Bash
   1	zcat results/fq/sample.fq.gz | head -20

Remora Errors¶

Model Not Found¶

Error:

1

FileNotFoundError: remora model not found

Solution:

Verify the model path in config:

1

remora_cca_classifier: "resources/models/cca_classifier.pt"

Ensure the file exists:

1

ls -la resources/models/cca_classifier.pt

Kmer Table Error¶

Error:

1

Error loading kmer table

Solution:

Verify kmer table path:

1

remora_kmer_table: "resources/kmers/9mer_levels_v1.txt"

Snakemake Errors¶

Locked Directory¶

Error:

1

Directory cannot be locked

Solution:

1

pixi run snakemake --unlock --configfile=config/config.yml

Missing Input Files¶

Error:

1

MissingInputException

Solutions:

1. Check if prerequisite rules completed
2. Verify file paths in config
3. Run a dry-run to check DAG:

   Bash
   1	pixi run snakemake -n --configfile=config/config.yml

Rule Failed¶

Error:

1

Error in rule <rule_name>

Solution:

1. Check the rule log:

   Bash
   1	cat results/logs/<rule_name>/<sample>

2. Re-run with verbose output:

   Bash
   1	pixi run snakemake -p --configfile=config/config.yml

Configuration Errors¶

Sample File Parse Error¶

Error:

1

Error parsing samples file

Solutions:

1. For TSV: Ensure tab-separated (not spaces)
2. For YAML: Check indentation
3. Validate with:

   Bash
   1 2 3 4 5	# TSV cat -A config/samples.tsv # Shows ^I for tabs # YAML python -c "import yaml; yaml.safe_load(open('config/samples.yml'))"

Config Key Missing¶

Error:

1

KeyError: '<key>'

Solution:

Ensure your config inherits from base:

1
2

# Your config should be used with --configfile
# Base config is loaded automatically by Snakefile

WarpDemuX Errors¶

WarpDemuX Not Found¶

Error:

1

warpdemux: command not found

Solution:

Install WarpDemuX via the setup command:

1

pixi run setup

Invalid Barcode Kit¶

Error:

1

Invalid barcode kit name

Solution:

Use a valid kit name:

• WDX4_tRNA_rna004_v1_0
• WDX4b_tRNA_rna004_v1_0

No Reads for Barcode¶

Error: Sample has 0 reads after demultiplexing.

Solutions:

1. Verify barcode assignment in YAML file
2. Check demux summary:

   Bash
   1	zcat results/demux/read_ids/run_id/demux_summary.tsv.gz

3. Ensure barcode kit matches library prep

File System Errors¶

Disk Full¶

Error:

1

No space left on device

Solutions:

1. Check disk usage:

   Bash
   1	df -h .

2. Clean intermediate files:

   Bash
   1	rm -rf results/bam/rebasecall results/bam/aln results/fq

3. Use a different output directory

Permission Denied¶

Error:

1

PermissionError: [Errno 13] Permission denied

Solutions:

1. Check file permissions:

   Bash
   1	ls -la <file>

2. Verify write access to output directory