Troubleshooting Guide

This guide covers common issues and their solutions when using Auto-M4B.

Quick Diagnostics

Validate Your Configuration First

Always start here - validate your configuration before troubleshooting:

docker-compose run --rm auto-m4b pipenv run python -m src --validate

This checks:

✅ All required directories exist and are accessible
✅ Numeric values are valid (CPU_CORES > 0, etc.)
✅ m4b-tool is available
✅ Configuration values are properly formatted

If validation fails, fix the reported errors first before investigating further.

Check Container Status

# Is the container running?
docker-compose ps

# View recent logs
docker-compose logs --tail=50 auto-m4b

# Follow logs in real-time
docker-compose logs -f auto-m4b

Enable Debug Mode

Add to your docker-compose.yml:

environment:
  - DEBUG=Y

Then restart:

docker-compose down
docker-compose up -d

Common Issues

1. Container Won't Start

Symptom

Container exits immediately or shows Exited (1) status.

Diagnosis

docker-compose logs auto-m4b

Common Causes & Solutions

Missing required folders:

Error: INBOX_FOLDER is not set

Solution: Set all required folder paths in environment:

environment:
  - INBOX_FOLDER=/inbox
  - CONVERTED_FOLDER=/converted
  - ARCHIVE_FOLDER=/archive
  - BACKUP_FOLDER=/backup

Invalid folder paths:

Error: /inbox does not exist and could not be created

Solution: Ensure volume mounts point to existing directories:

mkdir -p ~/audiobooks/{inbox,converted,archive,backup}

m4b-tool not found:

Error: Could not find 'm4b-tool' in PATH

Solution: The Docker image includes m4b-tool. If you see this error, you may be running outside Docker. Use the Docker image or install m4b-tool manually.

2. Permission Errors

Symptom

PermissionError: [Errno 13] Permission denied

Or files owned by root instead of your user.

Diagnosis

# Check file ownership in your folders
ls -la ~/audiobooks/inbox/
ls -la ~/audiobooks/converted/

# Check your user ID
id

Solutions

Fix PUID/PGID:

Find your user's UID/GID:

id
# uid=1026(yourname) gid=1000(yourname)

Update docker-compose.yml:

environment:
  - PUID=1026
  - PGID=1000

Fix existing file ownership:
```
sudo chown -R 1026:1000 ~/audiobooks/
```

Restart container:

docker-compose down
docker-compose up -d

3. Books Not Being Processed

Symptom

Books added to inbox folder are ignored or not detected.

Diagnosis

# Check if Auto-M4B sees the files
docker-compose logs auto-m4b | grep -i "found\|scanning"

# Verify file structure
ls -la ~/audiobooks/inbox/

Common Causes & Solutions

Wrong folder structure:

Auto-M4B expects:

inbox/
└── BookName/
    ├── Chapter01.mp3
    ├── Chapter02.mp3
    └── ...

Not:

inbox/
├── Chapter01.mp3    # ❌ Standalone files should be in subfolder
└── Chapter02.mp3

Solution: Create a subfolder for each book:

mkdir ~/audiobooks/inbox/MyBook
mv ~/audiobooks/inbox/*.mp3 ~/audiobooks/inbox/MyBook/

Unsupported file format:

Check file extensions:

file ~/audiobooks/inbox/MyBook/*

Supported: .mp3, .m4a, .m4b, .ogg, .wma

Match filter active:

If you have MATCH_FILTER set, only matching books are processed.

Check your configuration:

environment:
  # - MATCH_FILTER=Dresden.*  # Comment out or remove

Files still being copied:

Auto-M4B waits for file modifications to stop (WAIT_TIME) before processing.

Solution: Wait a few seconds after copying completes, or increase WAIT_TIME:

environment:
  - WAIT_TIME=10

4. Conversion Failures

Symptom

Book processing starts but fails with errors.

Diagnosis

# Check for error messages
docker-compose logs auto-m4b | grep -i "error\|failed"

# Look for the book in the inbox failure state
ls ~/audiobooks/inbox/.failed/

Common Causes & Solutions

Corrupted audio files:

Error: Could not decode audio file

Solution:

Check file integrity:
```
ffmpeg -v error -i file.mp3 -f null -
```
Re-download or replace corrupted files
Move fixed book back to inbox

Insufficient disk space:

Error: No space left on device

Solution:

Check disk usage:
```
df -h
```
Free up space or adjust folder locations
Consider disabling backup:
```
environment:
  - BACKUP=N
```

Complex folder structure:

Warning: Nested subfolders detected

Solution: Auto-M4B handles nested folders, but deeply nested or complex structures may cause issues. Flatten the structure:

# Before: Book/Disc1/Chapter01.mp3, Book/Disc2/Chapter01.mp3
# After: Book/Disc1-Chapter01.mp3, Book/Disc2-Chapter01.mp3

find Book/ -type f -name "*.mp3" -exec mv {} Book/ \;

Or enable the beta feature:

environment:
  - FLATTEN_MULTI_DISC_BOOKS=Y

m4b-tool errors:

Error: m4b-tool merge failed

Solution:

Enable debug mode: DEBUG=Y
Check logs for specific m4b-tool error
Verify m4b-tool version:
```
docker exec auto-m4b m4b-tool --version
```
Ensure you have v0.5-prerelease (required)

5. Slow Conversion Speed

Symptom

Conversion takes a very long time.

Diagnosis

# Check CPU usage
docker stats auto-m4b

# Check configured CPU cores
docker exec auto-m4b env | grep CPU_CORES

Solutions

Increase CPU cores:

environment:
  - CPU_CORES=8  # Use more cores

Don't exceed your system's core count:

# Check available cores
nproc

Use faster storage:

Move WORKING_FOLDER to SSD:

environment:
  - WORKING_FOLDER=/mnt/nvme/auto-m4b

Large file optimization:

For very large audiobooks (>1GB), ensure you have:

Adequate RAM (4GB+ recommended)
Fast storage for working directory
Multiple CPU cores allocated

6. Chapter Issues

Symptom

Chapters have wrong names, lengths, or are missing.

Diagnosis

# Check chapter file
cat ~/audiobooks/converted/BookName/BookName.chapters.txt

Solutions

Wrong chapter names:

Enable filename-based chapters:

environment:
  - USE_FILENAMES_AS_CHAPTERS=Y

Or manually edit chapters:

Find .chapters.txt in converted folder
Edit chapter names
Move entire book folder to inbox
Auto-M4B will re-chapterize

Missing chapters:

Ensure all audio files are valid:

# Test each file
for f in ~/audiobooks/inbox/BookName/*.mp3; do
    echo "Testing: $f"
    ffmpeg -v error -i "$f" -f null - 2>&1
done

7. Docker-Specific Issues

Container keeps restarting

# Check restart loop
docker-compose ps

# See why it's crashing
docker-compose logs auto-m4b

Common causes:

Fatal error on last run (check for fatal.log)
Invalid configuration
Missing dependencies

Solution:

# Remove fatal lock file
docker exec auto-m4b rm /tmp/auto-m4b/fatal.log

# Or manually:
rm /path/to/working/folder/fatal.log

# Restart
docker-compose restart

Volume mount issues

Error: /inbox is not writable

Solution: Check volume mounts in docker-compose.yml:

volumes:
  - ~/audiobooks/inbox:/inbox:rw  # Ensure :rw (read-write)

Network issues (if using named network)

Error: network auto-m4b_default not found

Solution:

# Recreate network
docker-compose down
docker-compose up -d

8. Output/Converted Folder Issues

Books not appearing in converted folder

Check ON_COMPLETE setting:

environment:
  - ON_COMPLETE=archive  # Should move to archive after conversion

Check logs for move operation:

docker-compose logs auto-m4b | grep -i "moving to converted"

Duplicate files

Solution: Set overwrite behavior:

environment:
  - OVERWRITE_EXISTING=Y  # Overwrite existing files

Or:

environment:
  - OVERWRITE_EXISTING=N  # Skip existing files (default)

9. Memory Issues

Symptom

Error: Cannot allocate memory

Solutions

Increase Docker memory limit:

In Docker Desktop:

Settings → Resources → Memory → Increase to 4GB+

Or in docker-compose.yml:

services:
  auto-m4b:
    mem_limit: 4g

Process smaller batches:

Use MAX_LOOPS to process fewer books at a time:

docker exec auto-m4b python -m src --max_loops 1

10. Logs and Debugging

Enable verbose logging

environment:
  - DEBUG=Y

Save logs to file

# Continuous logging
docker-compose logs -f auto-m4b > auto-m4b.log

# Or check the global log file
cat ~/audiobooks/converted/auto-m4b.log

Check specific operations

# Find errors
docker-compose logs auto-m4b | grep -i error

# Find specific book
docker-compose logs auto-m4b | grep "BookName"

# Find conversion operations
docker-compose logs auto-m4b | grep -i "converting\|merge"

Advanced Troubleshooting

Run m4b-tool manually

Test m4b-tool directly:

docker exec -it auto-m4b bash

# Inside container
m4b-tool --version
m4b-tool merge /inbox/BookName --output-file=/tmp/test.m4b

Inspect container

# Open shell in container
docker exec -it auto-m4b bash

# Check environment
env | grep -E "(INBOX|CONVERTED|PUID)"

# Check file permissions
ls -la /inbox /converted

# Check processes
ps aux

Reset everything

If all else fails:

# Stop and remove container
docker-compose down

# Remove volumes (⚠️ deletes data)
docker-compose down -v

# Rebuild image
docker-compose build --no-cache

# Start fresh
docker-compose up -d

Check for known issues

Search GitHub issues: https://github.com/DarthDobber/auto-m4b/issues

Getting Help

If you've tried the solutions above and still have issues:

Enable debug mode: DEBUG=Y

Collect information:

# System info
docker --version
docker-compose --version
uname -a

# Container info
docker-compose ps
docker-compose logs --tail=100 auto-m4b

# Configuration
cat docker-compose.yml

Create a GitHub issue: Report a bug

Include:

Description of the problem
Steps to reproduce
Debug logs
System information
docker-compose.yml (remove sensitive data)

Prevention Tips

Regular maintenance

# Periodically clean working directory
docker exec auto-m4b rm -rf /tmp/auto-m4b/*

# Check disk space regularly
df -h

# Monitor logs for warnings
docker-compose logs auto-m4b | grep -i warning

Best practices

Test first: Use TEST=Y mode before processing your entire library
Keep backups: Enable BACKUP=Y until you're confident
Monitor disk space: Ensure adequate space for conversion (3x book size recommended)
Update regularly: Pull latest Docker image periodically
Use version tags: Pin to specific versions in production

services:
  auto-m4b:
    image: darthdobber/auto-m4b:v1.0.0  # Pin version

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Quick Diagnostics

Validate Your Configuration First

Check Container Status

Enable Debug Mode

Common Issues

1. Container Won't Start

Symptom

Diagnosis

Common Causes & Solutions

2. Permission Errors

Symptom

Diagnosis

Solutions

3. Books Not Being Processed

Symptom

Diagnosis

Common Causes & Solutions

4. Conversion Failures

Symptom

Diagnosis

Common Causes & Solutions

5. Slow Conversion Speed

Symptom

Diagnosis

Solutions

6. Chapter Issues

Symptom

Diagnosis

Solutions

7. Docker-Specific Issues

Container keeps restarting

Volume mount issues

Network issues (if using named network)

8. Output/Converted Folder Issues

Books not appearing in converted folder

Duplicate files

9. Memory Issues

Symptom

Solutions

10. Logs and Debugging

Enable verbose logging

Save logs to file

Check specific operations

Advanced Troubleshooting

Run m4b-tool manually

Inspect container

Reset everything

Check for known issues

Getting Help

Prevention Tips

Regular maintenance

Best practices

See Also