Troubleshooting

This guide covers common issues you might encounter when using Journiv and how to resolve them.

Installation Issues

Container Won't Start

Symptoms: Docker container exits immediately or fails to start.

Solutions:

1. Check logs:

   docker logs journiv

2. Verify required environment variables:

   • Ensure SECRET_KEY is set (minimum 32 characters)
   • Ensure DOMAIN_NAME is set
   • Check for typos in variable names

3. Check port availability:

   # Check if port 8000 is in use
   lsof -i :8000
   # Or on Windows
   netstat -ano | findstr :8000

   Change the port if needed: -p 8080:8000

4. Verify Docker is running:

   docker ps

Permission Errors

Symptoms: Container starts but can't write to /data directory.

Solutions:

1. For bind mounts:

   chmod -R 755 /path/to/data
   chown -R $(id -u):$(id -g) /path/to/data

2. For named volumes, Docker handles permissions automatically. If issues persist:

   docker volume inspect journiv_data

Database Connection Issues

Symptoms: Errors about database connection or migrations failing.

Solutions:

1. SQLite:

   • Ensure /data volume is writable
   • Check disk space: df -h
   • Verify database file permissions

2. PostgreSQL:

   • Verify PostgreSQL is running: docker compose ps postgres
   • Check DATABASE_URL format: postgresql://user:password@host:5432/dbname
   • Test connection: docker compose exec journiv python -c "from app.core.database import engine; engine.connect()"
   • Check PostgreSQL logs: docker compose logs postgres

Application Issues

Can't Access Web Interface

Symptoms: Browser shows connection refused or timeout.

Solutions:

1. Verify container is running:

   docker ps | grep journiv

2. Check port mapping:

   docker port journiv

   Should show 8000/tcp -> 0.0.0.0:8000

3. Check firewall:

   # Linux
   sudo ufw status
   sudo iptables -L

4. Try accessing from container:

   docker compose exec journiv curl http://localhost:8000/health

Media Files Not Uploading

Symptoms: Upload fails or files don't appear.

Solutions:

1. Check file size limits:

   • Default: 50MB (MAX_FILE_SIZE_MB)
   • Increase if needed: MAX_FILE_SIZE_MB=100

2. Verify media directory permissions:

   docker compose exec journiv ls -la /data/media

3. Check disk space:

   docker compose exec journiv df -h /data

4. Verify file types:

   • Images: JPEG, PNG, GIF, WebP
   • Videos: MP4, MOV, WebM
   • Audio: MP3, WAV, M4A

Search Not Working

Symptoms: Search returns no results or is slow.

Solutions:

1. For slow search:

   • Switch to PostgreSQL for better performance
   • Ensure database indexes are created (migrations run)
   • Consider archiving old entries

2. For no results:

   • Check search filters aren't too restrictive
   • Verify entries exist in the database
   • Try searching without filters first

OIDC Authentication Issues

Symptoms: OIDC login fails or redirects incorrectly.

Solutions:

1. Verify configuration:

   • OIDC_ENABLED=true
   • OIDC_ISSUER is correct and accessible
   • OIDC_CLIENT_ID and OIDC_CLIENT_SECRET are correct
   • OIDC_REDIRECT_URI matches provider configuration
   • REDIS_URL is set (required for OIDC)

2. Check Redis:

   docker compose ps redis
   docker compose logs redis

3. Verify redirect URI:

   • Must match exactly in OIDC provider
   • Format: https://your-domain.com/api/v1/oidc/callback

4. Check OIDC provider logs:

   • Review provider logs for authentication errors
   • Verify scopes are correct: openid email profile

Mobile App Issues

Can't Connect to Server

Symptoms: Mobile app can't connect to your Journiv instance.

Solutions:

1. Verify server URL:

   • Include http:// or https://
   • Use correct IP or domain
   • Check port if not using standard ports

2. Check network connectivity:

   • Ensure device is on same network (for local IPs)
   • Test URL in browser: http://your-server:8000/health

3. Enable CORS (if accessing from different domain):

   ENABLE_CORS=true
   CORS_ORIGINS=https://your-domain.com

4. Check firewall:

   • Ensure port 8000 (or your port) is open
   • Verify firewall allows connections

Offline Sync Issues

Symptoms: Entries created offline don't sync.

Solutions:

1. Check connectivity:

   • Verify internet connection
   • Test server accessibility

2. Force sync:

   • Pull down to refresh in the app
   • Check sync status in settings

3. Clear cache (if needed):

   • App settings → Clear cache
   • Re-login if necessary

Performance Issues

Slow Loading

Symptoms: Pages or API requests are slow.

Solutions:

1. Database optimization:

   • Switch to PostgreSQL for better performance
   • Ensure indexes are created
   • Run VACUUM on SQLite: docker compose exec journiv sqlite3 /data/journiv.db VACUUM;

2. Resource limits:

   • Increase container memory: --memory=2g
   • Check CPU usage: docker stats journiv

3. Media optimization:

   • Compress images before uploading
   • Use appropriate video formats
   • Consider CDN for media (advanced)

High Memory Usage

Symptoms: Container uses excessive memory.

Solutions:

1. Set memory limits:

   services:
     journiv:
       mem_limit: 2g

2. Check for memory leaks:

   • Monitor memory over time
   • Restart container if needed
   • Review application logs

Backup & Restore Issues

Backup Fails

Symptoms: Backup command fails or creates incomplete backups.

Solutions:

1. Check disk space:

   df -h

2. Verify permissions:

   docker compose exec journiv ls -la /data

3. Use export feature:

   • Use web UI export instead
   • Or API export endpoint

Restore Fails

Symptoms: Restored data doesn't appear or is corrupted.

Solutions:

1. Verify backup integrity:

   tar -tzf backup.tar.gz

2. Check database migrations:

   docker compose exec journiv alembic current
   docker compose exec journiv alembic upgrade head

3. Restore step by step:

   • Stop container
   • Restore files
   • Start container
   • Verify migrations

Getting More Help

If you're still experiencing issues:

1. Check logs:

   docker compose logs journiv
   docker compose logs --tail=100 -f journiv

2. Review documentation:

   • FAQ
   • Configuration

3. Community support:

   • Discord
   • GitHub Issues
   • Reddit

4. Report bugs:

   • Include error messages
   • Steps to reproduce
   • Your environment (Docker version, OS, etc.)
   • Relevant logs