Troubleshooting

VFS / Mount Issues

Mount point not visible on host

Symptom: Files appear inside the container but /mnt/riven is empty on the host.

Fix: Ensure mount propagation is set up correctly:

1. Check the systemd service is running:

sudo systemctl status riven-mount.service

2. Verify propagation:

findmnt -o TARGET,PROPAGATION /mnt/riven
# Must show "shared"

3. Ensure the Docker volume mount uses rshared:

volumes:
  - /mnt/riven:/mount:rshared,z

4. Ensure RIVEN_SETTING__vfsMountPath matches the container-side path (/mount above), not the host path.

"Transport endpoint is not connected"

Symptom: Accessing /mnt/riven gives a "Transport endpoint is not connected" error.

Fix: The FUSE mount was interrupted. Restart the container:

docker compose restart riven

If that doesn't work, manually unmount and restart:

sudo fusermount -uz /mnt/riven
docker compose restart riven

Permission denied on /dev/fuse

Ensure the container has the required capabilities:

cap_add:
  - SYS_ADMIN
security_opt:
  - apparmor:unconfined
devices:
  - /dev/fuse

Database Issues

Connection refused to PostgreSQL

Check that PostgreSQL is healthy before Riven starts:

depends_on:
  postgres:
    condition: service_healthy

Verify the connection URL matches your PostgreSQL credentials:

RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:password@postgres:5432/riven"

The host is the compose service name, not localhost — localhost inside the Riven container refers to the Riven container.

Migration errors

Riven runs migrations automatically on startup. If a migration fails:

1. Check the logs: docker compose logs riven
2. Ensure you're running the latest version: docker compose pull
3. If the database is corrupted, you may need to reset it (data loss):

docker compose down -v  # Removes volumes!
docker compose up -d

API Issues

Connection refused on port 3000

Symptom: The container is healthy and the port is published, but requests to http://<host>:3000 are refused. Anything that calls into Riven — the Seerr webhook, a reverse proxy — fails.

Fix: gqlHost defaults to localhost, so the API binds to loopback inside the container and publishing the port has no effect. Bind it to all interfaces:

RIVEN_SETTING__gqlHost="0.0.0.0"

Plugin Issues

Plugin not starting

Check the logs for validation errors:

docker compose logs riven | grep -i plugin

Common causes:

• The plugin isn't listed in RIVEN_SETTING__enabledPlugins
• Missing API key environment variable
• Invalid API key (expired or wrong permissions)
• Target service is unreachable from the container

"API token is not set"

The plugin's environment variable is not set or empty. Check your .env file:

# Correct format
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-key"

# Common mistakes:
# Missing quotes around values with special characters
# Extra spaces around the = sign
# Wrong plugin name (case-sensitive)

Redis Issues

Redis connection refused

Ensure Redis is running and healthy:

docker compose ps redis
docker compose logs redis

Check the Redis URL:

RIVEN_SETTING__redisUrl="redis://redis:6379"

Media Server Issues

Plex/Jellyfin doesn't see new files

1. Verify VFS is mounted: ls /mnt/riven should show files
2. Check the media server volume mount uses rslave:

volumes:
  - /mnt/riven:/mount:rslave,z

3. Trigger a library scan in your media server
4. Ensure plexLibraryPath / jellyfinLibraryPath matches the path as the media server sees it (/mount above)

Docker Issues

Container keeps restarting

Check the logs:

docker compose logs --tail=50 riven

Common causes:

• Missing required environment variables
• Database not reachable
• Redis not reachable
• Invalid VFS mount path
• The bind-mounted logs or data directory is not writable by UID 1000

Getting Help

• Check the GitHub Issues
• Join the Discord Server
• Email contact@riven.tv