Skip to main content

Troubleshooting

Where are the logs?​

Docker:

docker compose logs -f cinephage

Web Interface:

Settings → System → Logs

Log Files:

./config/logs/cinephage.log

How do I enable debug logging?​

Docker:

environment:
  - LOG_LEVEL=debug

Restart required:

docker compose restart

My database is getting large, what should I do?​

Check size:

ls -lh ./config/data/cinephage.db

Optimize:

# Docker
docker exec cinephage sqlite3 /config/data/cinephage.db "VACUUM;"

# Native
sqlite3 ./data/cinephage.db "VACUUM;"

Set retention:

Settings → System → Data Retention

Cinephage won't start, what do I do?​

Check logs:

docker compose logs cinephage

Common issues:

  1. Port already in use - Change port mapping
  2. Database locked - Check no other instance running
  3. Permission denied - Fix PUID/PGID or file permissions
  4. Out of memory - Increase Docker memory limit

Reset (last resort):

# Backup first
cp -r ./config ./config-backup

# Reset database
docker compose down
rm ./config/data/cinephage.db
docker compose up -d

How do I reset my password?​

If you can't log in:

  1. Stop Cinephage
  2. Delete user from database (advanced) or
  3. Reset entire database (loses all data) or
  4. Use CLI reset command (if available)

Why are my subtitle searches failing?​

Check:

  1. Subtitle providers configured
  2. Language profile includes desired languages
  3. Video file name is clear (not obfuscated)
  4. Subtitle providers have the language

Can I use a VPN?​

Yes, but don't use Cinephage's built-in VPN (there isn't one). Instead:

Option 1: VPN Container

services:
  gluetun:  # VPN container
    image: qmcgaw/gluetun
    # ... VPN config
  
  cinephage:
    network_mode: service:gluetun

Option 2: System VPN

  • Run VPN on your host
  • Cinephage traffic goes through automatically

How do I get help?​

Resources:

When asking for help, include:

  1. What you were trying to do
  2. What actually happened
  3. Error messages (from logs)
  4. Your configuration (sanitized)
  5. Cinephage version

Advanced Topics​

Can I use PostgreSQL instead of SQLite?​

Not currently. Cinephage uses SQLite for simplicity. PostgreSQL support may be added in the future for very large libraries.

Can I run multiple instances?​

Not recommended. SQLite doesn't handle concurrent access well. If you need multiple instances, use separate databases.

Is there an API?​

Yes, but it's currently private and undocumented. Public API documentation will be released in the future.

Can I contribute?​

Yes! Cinephage is open source:

  • 🐛 Report bugs on GitHub
  • 💡 Suggest features
  • 📝 Improve documentation
  • 💻 Submit pull requests

See Contributing.

What's the roadmap?​

Check the GitHub repository for:

  • Active development
  • Feature requests
  • Known issues
  • Release notes

Quick Command Reference​

View logs:

docker compose logs -f cinephage

Restart Cinephage:

docker compose restart cinephage

Update Cinephage:

docker compose pull && docker compose up -d

Backup database:

cp ./config/data/cinephage.db ./config/data/cinephage-backup.db

Check database:

sqlite3 ./config/data/cinephage.db ".tables"

Optimize database:

sqlite3 ./config/data/cinephage.db "VACUUM;"

See Also​