Troubleshooting Guide

This guide covers common issues and their solutions when running Magi.

Installation Issues

Binary Won't Run

Symptoms: Permission denied or command not found

Solution:

# Make binary executable
chmod +x magi

# Verify it's executable
ls -la magi

# Run with explicit path
./magi

Port Already in Use

Symptoms: Error: listen tcp :3000: bind: address already in use

Solution:

Find what's using the port:

# Linux/macOS
sudo lsof -i :3000
sudo ss -tulpn | grep 3000

# Windows (PowerShell)
netstat -ano | findstr :3000

Change Magi's port:

PORT=8080 ./magi

Missing Dependencies

Symptoms: error while loading shared libraries

Solution:

Linux:

# Install common dependencies
sudo apt install libsqlite3-0  # Debian/Ubuntu
sudo dnf install sqlite-libs   # Fedora/RHEL

Windows: Install Microsoft Visual C++ Redistributable

Database Problems

Database Locked

Symptoms: database is locked errors in logs

Cause: Multiple Magi instances accessing the same database

Solution: 1. Stop all Magi instances 2. Ensure only one instance runs per database 3. Check for orphaned processes: ps aux | grep magi

Corrupted Database

Symptoms: database disk image is malformed, crashes on startup

Solution:

Check integrity:

sqlite3 ~/magi/magi.db "PRAGMA integrity_check;"

Attempt repair:

sqlite3 ~/magi/magi.db ".recover" | sqlite3 ~/magi/magi_recovered.db

Restore from backup:

# Stop Magi
cp ~/backups/magi.db ~/.local/share/magi/magi.db
# Start Magi

Last resort - Reset database (⚠️ Deletes all data):

rm ~/.local/share/magi/magi.db

Database Inspection

Access database:

# Install SQLite tools
sudo apt install sqlite3  # Debian/Ubuntu
sudo dnf install sqlite   # Fedora/RHEL

# Open database
sqlite3 ~/magi/magi.db

Common queries:

-- View tables
.tables

-- View schema
.schema

-- Count manga
SELECT COUNT(*) FROM mangas;

-- Count users
SELECT COUNT(*) FROM users;

-- View all users
SELECT username, role, banned FROM users;

-- Check configuration
SELECT * FROM app_config;

-- Exit
.quit

Indexing Issues

Library Won't Index

Symptoms: Library shows 0 manga, indexing completes but nothing added

Causes and solutions:

1. Incorrect Path

# Verify path exists
ls -la /path/to/manga

# Check Docker volume mounts
docker inspect magi | grep Mounts -A 20

2. Permission Denied

# Check file permissions
ls -la /path/to/manga

# Fix permissions (Linux)
chmod -R 755 /path/to/manga
chown -R magi:magi /path/to/manga

# Docker: ensure volume is readable
docker run --rm -v /path/to/manga:/data:ro busybox ls -la /data

3. No Supported Files

Magi requires: - CBZ, CBR, ZIP, or RAR files - Or directories containing images

Verify structure:

/manga/
├── Series Name/          # Folder with manga name
│   ├── Chapter 1.cbz    # Chapter files
│   └── Chapter 2.cbz

4. Invalid File Names

Problematic names: - Non-UTF-8 characters - Very long filenames - Special characters: <>:"|?*

Fix:

# Rename files with problematic characters
find /path/to/manga -name '*[<>:"|?*]*' -print

Manga Not Found on MangaDex

Symptoms: Manga indexed but no metadata or cover art

Solutions:

Manual metadata update:
Open manga page
Click Update Metadata (moderator/admin)
Search for correct manga
Apply metadata
Manual edit:
Click Manual Edit
Enter title, author, description manually
Save
Offline mode: Magi uses folder names if no metadata found. This is normal for:
Unlicensed manga
Very new releases
Non-English manga

Slow Indexing

Symptoms: Indexing takes hours for moderate collections

Causes and solutions:

1. Slow Internet

Metadata fetching requires internet. Each manga queries MangaDex API.

Solution: Be patient or index during off-peak hours.

2. Slow Disk I/O

Cover art downloads and archive extraction are disk-intensive.

Solution: - Use SSD storage - Reduce concurrent operations - Index one library at a time

3. Large RAR Archives

RAR files are slow for random access.

Solution: Convert to CBZ:

# Extract and recompress as ZIP
for f in *.cbr; do
    mkdir temp
    unrar x "$f" temp/
    cd temp
    zip -r "../${f%.cbr}.cbz" *
    cd ..
    rm -rf temp
done

Duplicate Detection Issues

Symptoms: Same manga indexed multiple times

Cause: Multiple folders with similar names, or same files in different libraries

Solution:

Check Admin > Duplicates (if available)
Manually delete unwanted duplicates:
Open duplicate manga
Click Delete (admin only)
Reorganize folders to avoid duplicates

Reading and Display Issues

Images Not Loading

Symptoms: Blank pages, broken images in reader

Causes and solutions:

1. Archive Extraction Failed

Check logs:

# Docker
docker logs magi

# Systemd
journalctl -u magi -f

# Direct run
# Check terminal output

Solution: Re-index manga to retry extraction.

2. Cached Data Corruption

Clear cache:

# Stop Magi
rm -rf ~/.local/share/magi/cache/*
# Start Magi

3. File Permissions

Verify Magi can read files:

ls -la /path/to/manga/SeriesName/Chapter.cbz

# Test extraction manually
unzip -t /path/to/manga/SeriesName/Chapter.cbz

Reader Controls Not Working

Symptoms: Keyboard shortcuts don't work, navigation broken

Solutions:

Reload page: Press F5 or Ctrl+R
Clear browser cache: Ctrl+Shift+Delete
Check JavaScript: Ensure JavaScript is enabled
Try different browser: Test in Chrome/Firefox

Cover Art Missing

Symptoms: Manga has no cover image, shows placeholder

Causes:

MangaDex API issue: Try updating metadata
Network error during download: Re-index manga
Cache cleared: Will re-download on next access

Solution:

# Force cover re-download
# Option 1: Re-index manga
Click "Refresh Metadata" on manga page

# Option 2: Delete cached cover
rm ~/.local/share/magi/cache/covers/manga-slug.jpg

Wrong Chapter Order

Symptoms: Chapters listed in incorrect order

Cause: Chapter naming doesn't sort naturally

Examples of problematic naming: - Chapter 1, Chapter 10, Chapter 2 (string sort) - Mixed formats: Ch 1, Chapter 2, Ep 3

Solution:

Rename chapters with zero-padded numbers:

# Example: Rename to 001, 002, etc.
for i in {1..99}; do
    mv "Chapter $i.cbz" "Chapter $(printf %03d $i).cbz"
done

Performance Problems

High Memory Usage

Symptoms: Magi using 2GB+ RAM, system slowdown

Solutions:

Docker - Limit memory:

docker run -d --memory=1g --memory-swap=2g alexbruun/magi:latest

Systemd - Limit memory:

[Service]
MemoryMax=1G
MemoryHigh=800M

Reduce collection size: - Split into multiple libraries - Index fewer manga at once

Slow Page Loading

Symptoms: Pages take seconds to load in reader

Causes and solutions:

1. Large Image Files

Some manga have huge images (10MB+ per page).

No direct solution, but Magi should cache after first load.

2. Slow Storage

Solution: Move manga to faster storage (SSD).

3. Network Latency

If accessing Magi over network, latency affects load times.

Solution: Use local network, not internet.

High CPU Usage

Symptoms: 100% CPU during indexing

This is normal during: - Initial indexing - Cover art download/processing - Archive extraction

If persistent after indexing: 1. Check for indexing loops (bad cron schedule) 2. Verify no corrupted archives causing retries 3. Restart Magi

Network and Access Issues

Can't Access from Other Devices

Symptoms: http://[server-ip]:3000 times out from other computers

Solutions:

1. Firewall Blocking Port

Linux (firewalld):

sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload

Linux (ufw):

sudo ufw allow 3000/tcp
sudo ufw reload

Windows:

New-NetFirewallRule -DisplayName "Magi" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow

2. Wrong IP Address

Find correct IP:

# Linux/macOS
ip addr show
ifconfig

# Windows
ipconfig

Use the IP from your local network (usually 192.168.x.x or 10.x.x.x).

3. Docker Network Mode

If using Docker's host network mode, IP should be the host's IP, not Docker's.

CORS Errors

Symptoms: Browser console shows CORS policy errors

Cause: Accessing Magi from different domain/port

Solution: Use reverse proxy (Nginx, Caddy) with proper CORS headers.

WebSocket Connection Failed

Symptoms: Job status not updating in real-time

Cause: Reverse proxy not forwarding WebSocket connections

Solution (Nginx):

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

User and Authentication Issues

Symptoms: "Invalid username or password" despite correct credentials

Solutions:

1. Password Typo

Double-check username and password (case-sensitive).

2. Account Banned

Ask admin to check: Admin > Users

3. Database Issue

# Check if user exists
sqlite3 ~/magi/magi.db "SELECT username, banned FROM users WHERE username='yourname';"

Logged Out Repeatedly

Symptoms: Session expires too quickly

Cause: Tokens expire after 15 minutes (by design)

Workaround: Stay active or login again.

Registration Disabled

Symptoms: "Registration is disabled" message

Cause: Admin disabled registration in config

Solution: Ask admin to enable registration temporarily, or have admin change your role.

Can't Change Password

Symptoms: No password change option in UI

Current limitation: Password changes not yet implemented in UI.

Workaround (admin):

# Manually reset password via database
# (Requires bcrypt hash generation - complex)

Advanced Debugging

Enable Debug Logging

Linux/macOS:

# Not currently configurable
# Check implementation for log level options

Docker:

docker logs -f magi

Systemd:

journalctl -u magi -f -n 100

Check Application Health

Test HTTP endpoint:

curl -v http://localhost:3000/

Expected: HTML response with status 200.

Verify File System

Check file system for errors:

# Linux - Check disk
sudo fsck /dev/sda1

# Check manga directory
ls -laR /path/to/manga | head -100

Network Debugging

Test connectivity:

# From same server
curl http://localhost:3000

# From another device
curl http://[server-ip]:3000

# Test DNS
nslookup magi.example.com

Database Debugging

Check database size:

du -h ~/.local/share/magi/magi.db

Analyze query performance:

sqlite3 ~/magi/magi.db
> EXPLAIN QUERY PLAN SELECT * FROM mangas;

Vacuum database:

sqlite3 ~/magi/magi.db "VACUUM;"

Container Debugging

Docker:

# Shell into container
docker exec -it magi /bin/sh

# Check environment
docker exec magi env

# Check processes
docker top magi

# Inspect container config
docker inspect magi

Podman:

# Similar commands, replace docker with podman
podman exec -it magi /bin/sh

Getting Help

If you're still stuck:

Check existing issues: GitHub Issues
Search discussions: GitHub Discussions
Create new issue: Include:
Magi version (./magi --version)
Operating system
Installation method (binary, Docker, etc.)
Relevant logs
Steps to reproduce
Ask questions: Post in Discussions for general help

Collecting Debug Information

When reporting issues, provide:

# Magi version
./magi --version

# OS info
uname -a

# Docker version (if using Docker)
docker --version

# Recent logs (last 100 lines)
journalctl -u magi -n 100 --no-pager

# Database stats
sqlite3 ~/magi/magi.db "SELECT COUNT(*) FROM mangas; SELECT COUNT(*) FROM users;"

# Disk space
df -h

Common Error Messages

`database schema version mismatch`

Solution: Database needs migration. Restart Magi (migrations run automatically).

`failed to fetch metadata: connection refused`

Solution: - Check internet connection - MangaDex may be down, try again later - Firewall blocking outbound HTTPS

`failed to extract archive: unsupported format`

Solution: - Archive may be corrupted - Unsupported compression method - Re-download or convert to standard CBZ

`permission denied: /data/magi/magi.db`

Solution: Fix file permissions (see Permission Errors above).

`context deadline exceeded`

Solution: - Request timed out (slow network/API) - Try again - Increase timeout (not currently configurable)

Preventive Maintenance

Avoid issues with regular maintenance:

Backup database weekly:

cp ~/.local/share/magi/magi.db ~/backups/

Monitor disk space:
```
df -h
```
Update Magi regularly: Stay on latest version for bug fixes.
Organize files properly: Consistent naming and structure reduces issues.
Test after changes: After configuration changes, verify everything works.

Known Issues

Track known issues and their status: GitHub Issues

Common known issues: - RAR archives slower than ZIP (by design) - Large collections (10,000+ manga) may be slow - Password change UI not yet implemented

Still having problems? Open an issue with detailed information, and the community will help!

Troubleshooting Guide

Table of Contents

Installation Issues

Binary Won't Run

Port Already in Use

Missing Dependencies

Database Problems

Database Locked

Corrupted Database

Database Inspection

Indexing Issues

Library Won't Index

1. Incorrect Path

2. Permission Denied

3. No Supported Files

4. Invalid File Names

Manga Not Found on MangaDex

Slow Indexing

1. Slow Internet

2. Slow Disk I/O

3. Large RAR Archives

Duplicate Detection Issues

Reading and Display Issues

Images Not Loading

1. Archive Extraction Failed

2. Cached Data Corruption

3. File Permissions

Reader Controls Not Working

Cover Art Missing

Wrong Chapter Order

Performance Problems

High Memory Usage

Slow Page Loading

1. Large Image Files

2. Slow Storage

3. Network Latency

High CPU Usage

Network and Access Issues

Can't Access from Other Devices

1. Firewall Blocking Port

2. Wrong IP Address

3. Docker Network Mode

CORS Errors

WebSocket Connection Failed

User and Authentication Issues

Can't Login

1. Password Typo

2. Account Banned

3. Database Issue

Logged Out Repeatedly

Registration Disabled

Can't Change Password

Advanced Debugging

Enable Debug Logging

Check Application Health

Verify File System

Network Debugging

Database Debugging

Container Debugging

Getting Help

Collecting Debug Information

Common Error Messages

database schema version mismatch

failed to fetch metadata: connection refused

failed to extract archive: unsupported format

permission denied: /data/magi/magi.db

context deadline exceeded

Preventive Maintenance

Known Issues

`database schema version mismatch`

`failed to fetch metadata: connection refused`

`failed to extract archive: unsupported format`

`permission denied: /data/magi/magi.db`

`context deadline exceeded`