Troubleshooting and FAQ

Troubleshooting and FAQ

1. Container execution fails with "Read-only file system" or "Error creating output directory"

Symptom

ERROR: Error creating output directory '/pub/...': Read-only file system

Cause

By default, Apptainer/Singularity only automatically binds the user's home directory ($HOME), /tmp, and the current working directory ($PWD). External storage mount points (such as /pub, /data, or /scratch) are not mapped into the container by default.

Solution

Provide the -B (bind) flag to map the host directory into the container:

apptainer exec -B /pub PMAT_v2.2.0.sif PMAT autoMito -i input.fa -o /pub/output ...

Alternatively, export the bind path variable in your shell configuration (~/.bashrc):

export APPTAINER_BINDPATH="/pub,/data"
export SINGULARITY_BINDPATH="/pub,/data"

---

2. BLASTn not found

Symptom

ERROR: Can't find blastn, please install it

Solution

Ensure blastn (NCBI BLAST+ suite, version > 2.10.0) is installed and included in your system PATH:

# Debian / Ubuntu
sudo apt-get install ncbi-blast+

# CentOS / RHEL / Rocky Linux
sudo yum install ncbi-blast+

# Conda environment
conda install -c bioconda blast

Alternatively, using the standalone PMAT_v2.2.0.sif container avoids this requirement, as BLASTn is already bundled inside the image.

---

3. Resolving complex assembly graphs with graphBuild

When autoMito generates fragmented contigs or fails to circularize the genome due to extremely high depth or repeat ambiguities:

1. Inspect the contig graph visualization in Bandage using output_dir/gfa_result/PMAT_mt_raw.gfa.
2. Identify candidate master contig IDs with high coverage.
3. Run graphBuild specifying the chosen seed IDs via -s and adjust the depth filtering threshold with -d.