Troubleshooting Guide

Docker Issues

Docker daemon not running

Symptom:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. 
Is the docker daemon running?

Solution:Linux:

sudo systemctl start docker
sudo systemctl enable docker  # Start on boot

macOS:

Open Docker Desktop from Applications
Wait for the whale icon to appear in the menu bar
Verify with: docker ps

Windows:

Launch Docker Desktop from Start menu
Wait for “Docker Desktop is running” notification
Verify with: docker ps

Verification:

docker --version
docker ps  # Should not show error

Port 8050 already in use

Symptom:

Error starting userland proxy: listen tcp4 127.0.0.1:8050: 
bind: address already in use

Cause: Another application or previous PROTÉGÉ PD instance is using port 8050.Solution 1: Find and stop the processLinux/macOS:

# Find process using port 8050
lsof -i :8050

# Kill the process (replace PID with actual process ID)
kill -9 <PID>

Windows:

# Find process using port 8050
netstat -ano | findstr :8050

# Kill the process (replace PID with actual process ID)
taskkill /PID <PID> /F

Solution 2: Use a different port

docker run --rm \
  --mount type=bind,source=/your/path/,target=/root/. \
  --name protege -p 127.0.0.1:8051:8050 --cpus 4 \
  ddelgadillo/protege_base:v1.0.2 \
  protege-pd -s myseqs.fna

Then access the application at http://127.0.0.1:8051Solution 3: Stop previous PROTÉGÉ container

docker stop protege
docker rm protege  # If not using --rm flag

Permission denied accessing Docker

Symptom:

Got permission denied while trying to connect to the Docker daemon socket

Linux Solution:

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or use:
newgrp docker

# Verify
docker ps

Temporary workaround:

sudo docker run --rm \
  --mount type=bind,source=/your/path/,target=/root/. \
  --name protege -p 127.0.0.1:8050:8050 --cpus 4 \
  ddelgadillo/protege_base:v1.0.2 \
  protege-pd -s myseqs.fna

Using sudo is not recommended for regular Docker usage. Fix permissions instead.

File Path and Mounting Issues

Cannot find input file (Linux/Mac)

Symptom:

FileNotFoundError: [Errno 2] No such file or directory: 'myseqs.fna'

Cause: File not in mounted directory or incorrect path specified.Solution:

Verify file exists:

ls -la /your/files/path/myseqs.fna

Use absolute paths for mounting:

# Bad (relative path)
--mount type=bind,source=./data,target=/root/.

# Good (absolute path)
--mount type=bind,source=/home/user/data,target=/root/.

Verify mount inside container:

docker run --rm \
  --mount type=bind,source=/home/user/data,target=/root/. \
  --name protege -p 127.0.0.1:8050:8050 --cpus 4 \
  ddelgadillo/protege_base:v1.0.2 \
  ls -la /root/

Use current directory shortcut:

cd /path/to/your/sequences
docker run --rm \
  --mount type=bind,source=$(pwd),target=/root/. \
  --name protege -p 127.0.0.1:8050:8050 --cpus 4 \
  ddelgadillo/protege_base:v1.0.2 \
  protege-pd -s myseqs.fna

Cannot find input file (Windows)

Symptom:

FileNotFoundError: [Errno 2] No such file or directory: 'myseqs.fna'

Windows-specific solutions:

Use forward slashes in Windows paths:

# Bad
--mount type=bind,source=C:\Users\Name\data,target=/root/.

# Good
--mount type=bind,source=C:/Users/Name/data,target=/root/.

Enable drive sharing in Docker Desktop:
- Open Docker Desktop Settings
- Go to “Resources” → “File Sharing”
- Add the drive containing your files (e.g., C:)
- Click “Apply & Restart”
PowerShell example:

docker run --rm `
  --mount type=bind,source=C:/Users/YourName/Documents/sequences,target=/root/. `
  --name protege -p 127.0.0.1:8050:8050 --cpus 4 `
  ddelgadillo/protege_base:v1.0.2 `
  protege-pd -s myseqs.fna

WSL2 users:

# Access Windows files from WSL2
cd /mnt/c/Users/YourName/sequences
docker run --rm \
  --mount type=bind,source=$(pwd),target=/root/. \
  --name protege -p 127.0.0.1:8050:8050 --cpus 4 \
  ddelgadillo/protege_base:v1.0.2 \
  protege-pd -s myseqs.fna

Read-only file system errors

Symptom:

OSError: [Errno 30] Read-only file system: 'sequences.csv'

Cause: Container cannot write output files to mounted directory.Solution:

Check directory permissions:

ls -ld /your/files/path/
chmod 755 /your/files/path/  # If needed

Ensure mount is not read-only:

# Add read-write explicitly (though it's default)
--mount type=bind,source=/your/path/,target=/root/.,readonly=false

Check Docker Desktop settings (Mac/Windows):
- Ensure file sharing is enabled for the directory
- Restart Docker Desktop

MUSCLE Alignment Issues

MUSCLE binary not found

Symptom:

FileNotFoundError: [Errno 2] No such file or directory: 'muscle_lin'

Cause: MUSCLE binary not in PATH or not executable.Solution:

Verify MUSCLE is installed:

docker exec -it protege which muscle_lin
# Should output: /usr/local/bin/muscle_lin

Check if executable:

docker exec -it protege ls -la /usr/local/bin/muscle_lin
# Should show: -rwxr-xr-x

Manually install if missing:

docker exec -it protege bash
cd /usr/local/bin
wget https://github.com/ddelgadillod/ProtegePD/raw/main/muscle/muscle_lin
chmod +x muscle_lin
exit

Rebuild image if persistent:

docker pull ddelgadillo/protege_base:v1.0.2

MUSCLE alignment fails with large datasets

Symptom:

Killed

MemoryError

Cause: Insufficient memory allocated to Docker.Solution:

Increase Docker memory (Docker Desktop):
- Open Docker Desktop Settings
- Go to “Resources” → “Advanced”
- Increase Memory to at least 4GB (8GB for large datasets)
- Click “Apply & Restart”
Increase CPUs for faster processing:

--cpus 8  # Instead of 4

Filter sequences before alignment:
- Reduce redundancy in input sequences
- Remove sequences with excessive gaps
- Use representative sequences for large datasets
Monitor resource usage:

docker stats protege

MUSCLE memory usage scales with sequence count and length. For >500 sequences, consider 8GB+ RAM.

Invalid amino acid translation errors

Symptom:

Bio.Data.CodonTable.TranslationError: Codon 'ATN' is invalid

Cause: Input sequences contain:

Non-standard nucleotides (N, R, Y, etc.)
Incorrect reading frame
Sequence length not divisible by 3

Solution:

Validate FASTA file:

# Check for non-ATGC characters
grep -v ">" myseqs.fna | grep -o "[^ATGC]" | sort -u

Verify sequence lengths:

# All should be divisible by 3 for coding sequences
grep -v ">" myseqs.fna | awk '{print length($0)}'

Clean sequences:
- Remove ambiguous nucleotides
- Ensure sequences are in-frame
- Verify sequences are protein-coding genes

PROTÉGÉ PD expects protein-coding genes in nucleotide format. Ensure your sequences are correctly annotated coding sequences (CDS).

Web Interface Issues

Browser cannot connect to 127.0.0.1:8050

Symptom:

“This site can’t be reached”
“Unable to connect”
“Connection refused”

Solution:

Verify container is running:

docker ps
# Should show 'protege' container

Check if port is mapped:

docker port protege
# Should show: 8050/tcp -> 127.0.0.1:8050

Check container logs:

docker logs protege
# Should show: "Running on http://0.0.0.0:8050/"

Wait for server startup:
- Initial alignment can take 1-5 minutes
- Watch logs: docker logs -f protege
- Look for “Dash is running on http://0.0.0.0:8050/”
Try different browser:
- Chrome: http://127.0.0.1:8050
- Firefox: http://127.0.0.1:8050
- Safari: http://127.0.0.1:8050
Check firewall:

# Linux
sudo ufw allow 8050

# macOS
# System Preferences → Security & Privacy → Firewall → Allow Docker

Dash application crashes or freezes

Symptom:

White screen
“Application Error”
Browser tab becomes unresponsive

Solution:

Check browser console (F12):
- Look for JavaScript errors
- Check Network tab for failed requests
Restart container:

docker stop protege
docker run --rm \
  --mount type=bind,source=/your/path/,target=/root/. \
  --name protege -p 127.0.0.1:8050:8050 --cpus 4 \
  ddelgadillo/protege_base:v1.0.2 \
  protege-pd -s myseqs.fna

Clear browser cache:
- Chrome: Ctrl+Shift+Delete → Clear cache
- Firefox: Ctrl+Shift+Delete → Clear cache
Reduce dataset complexity:
- Try with fewer sequences first
- Increase consensus threshold: -c 95
Check container resources:

docker stats protege
# Watch for memory/CPU spikes

Plots not displaying correctly

Symptom:

Empty graphs
Missing data points
Layout issues

Solution:

Wait for data processing:
- Plots appear after alignment completes
- Check console output for “CONTROL 5”, “CONTROL 6”, etc.
Verify consensus calculation:

docker logs protege | grep "Consensus"
# Should show consensus positions

Check for degeneracy filtering:
- Application filters primers with 0 degeneracies
- If no primers shown, try lower consensus: -c 80
Browser compatibility:
- Use modern browsers (Chrome 90+, Firefox 88+, Safari 14+)
- Enable JavaScript
- Disable ad blockers that might interfere
Check CSV output:

ls -la /your/files/path/protege_consensus.csv
# Verify file was created and has content

Installation and Update Issues

Image pull fails or is slow

Symptom:

Error response from daemon: Get https://registry-1.docker.io/v2/: 
net/http: TLS handshake timeout

Solution:

Check internet connection:

ping registry-1.docker.io

Restart Docker daemon:

# Linux
sudo systemctl restart docker

# Mac/Windows: Restart Docker Desktop

Use Docker mirror (China/slow connections):

# Add to /etc/docker/daemon.json
{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Pull with retry:

docker pull ddelgadillo/protege_base:v1.0.2 || \
docker pull ddelgadillo/protege_base:v1.0.2

Python package version conflicts

Symptom:

ImportError: cannot import name 'X' from 'module'
ModuleNotFoundError: No module named 'dash'

Cause: Outdated image or corrupted installation.Solution:

Pull latest image:

docker pull ddelgadillo/protege_base:v1.0.2

Remove old images:

docker images | grep protege
docker rmi <IMAGE_ID>  # Remove old versions

Verify Python packages:

docker run --rm ddelgadillo/protege_base:v1.0.2 pip3 list
# Check for: biopython 1.83, dash 2.14.2, pandas 2.2.0

Rebuild from source:

git clone https://github.com/ddelgadillod/ProtegePD.git
cd ProtegePD
docker build -t protege-local:latest .

Output and Results Issues

Output files not created

Symptom:

Missing protege_consensus.csv
Missing sequences.csv
Missing alSequences.csv

Solution:

Check container logs for errors:

docker logs protege | tail -50

Verify write permissions:

ls -ld /your/files/path/
chmod 755 /your/files/path/

Check if alignment completed:

docker logs protege | grep "Alignment length"
# Should show alignment statistics

Run with verbose flag:

protege-pd -s myseqs.fna -v

List files in container:

docker exec -it protege ls -la /root/

No primers with acceptable degeneracy

Symptom:

Empty plots after processing completes

Cause: Consensus threshold too strict or sequences too divergent.Solution:

Lower consensus threshold:

protege-pd -s myseqs.fna -c 80  # Default is 90

Adjust codon length:

protege-pd -s myseqs.fna -d 6  # Default is 7

Check sequence diversity:
- Too divergent: Consider using only closely related species
- Too similar: Primers will have low specificity
Review consensus CSV:

less protege_consensus.csv
# Check degeneracies column

Ideal primer degeneracy: 1-1024. Higher values indicate excessive sequence variation at that position.

Getting Additional Help

If your issue is not covered here:

Check container logs:

docker logs protege > protege_debug.log

Gather system information:

docker --version
docker info
uname -a  # Linux/Mac

Report the issue:
- GitHub: https://github.com/ddelgadillod/ProtegePD/issues
- Email: [email protected]
- Include: error messages, system info, sample input files (if possible)

Getting Started

Usage Guide

Core Concepts

Web Interface

Advanced

Docker Issues

File Path and Mounting Issues

MUSCLE Alignment Issues

Web Interface Issues

Installation and Update Issues

Output and Results Issues

Getting Additional Help

Build docs developers (and LLMs) love

Getting Started

Usage Guide

Core Concepts

Web Interface

Advanced

​Docker Issues

​File Path and Mounting Issues

​MUSCLE Alignment Issues

​Web Interface Issues

​Installation and Update Issues

​Output and Results Issues

​Getting Additional Help

Build docs developers (and LLMs) love

Docker Issues

File Path and Mounting Issues

MUSCLE Alignment Issues

Web Interface Issues

Installation and Update Issues

Output and Results Issues

Getting Additional Help