Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven-ts/llms.txt

Use this file to discover all available pages before exploring further.

Most Riven issues fall into a small number of categories: the VFS not mounting correctly, a service not being reachable, a missing environment variable, or a Docker permission problem. This page collects the symptoms, causes, and fixes for the issues reported most often. Start with the container logs — they almost always tell you exactly what went wrong: 
docker compose logs --tail=100 riven

​
VFS / FUSE Issues

Symptoms: Running ls /mnt/riven on the host shows nothing. Files appear when you docker compose exec riven ls /mount inside the container.Cause: The host mount point was not configured with shared propagation before Docker started, so the FUSE mount Riven creates inside the container cannot propagate outward.Fix:
  1. Verify the host-side propagation: 
    findmnt -o TARGET,PROPAGATION /mnt/riven
# Must show "shared" — if it shows "private" the fix below is needed
  2. Create and enable the systemd unit that makes the bind mount shared at boot:
    /etc/systemd/system/riven-mount.service
    [Unit]
Description=Make Riven data bind mount shared
After=local-fs.target
Before=docker.service

[Service]
Type=oneshot
ExecStart=/usr/bin/mount --bind /mnt/riven /mnt/riven
ExecStart=/usr/bin/mount --make-rshared /mnt/riven
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

    sudo systemctl daemon-reload
sudo systemctl enable --now riven-mount.service
  3. Confirm the Docker volume uses rshared (not rslave or shared): 
    volumes:
  - /mnt/riven:/mount:rshared,z
  4. Confirm RIVEN_SETTING__vfsMountPath is set to the container-side path (/mount), not the host path (/mnt/riven).
Symptoms: Any access to /mnt/riven on the host produces Transport endpoint is not connected. The directory exists but is inaccessible.Cause: The FUSE process inside the Riven container exited or was killed, leaving the mount point in a stale state. This happens after a crash, an OOM kill, or a forced container stop.Fix: Restart the container — vfsForceMount (enabled by default) will unmount and remount cleanly:
docker compose restart riven
If the restart fails because the stale mount blocks Docker from stopping the container, manually unmount first:
sudo fusermount -uz /mnt/riven
docker compose restart riven
Symptoms: The container exits immediately with a permission error referencing /dev/fuse or Operation not permitted in the FUSE init logs.Cause: The container is missing the SYS_ADMIN capability, the AppArmor profile is blocking FUSE operations, or the /dev/fuse device is not passed through.Fix: Ensure all three FUSE-related settings are present in your service definition:
cap_add:
  - SYS_ADMIN
security_opt:
  - apparmor:unconfined
devices:
  - /dev/fuse
On Ubuntu 24.04+, also verify that /dev/fuse exists on the host:
ls -la /dev/fuse
# If missing: sudo mknod -m 666 /dev/fuse c 10 229

​
Database Issues

Symptoms: Riven logs show connection refused or ECONNREFUSED pointing at the PostgreSQL host. The Riven container exits or enters a restart loop immediately.Cause: Either PostgreSQL is not yet ready when Riven starts (race condition), or the connection URL uses the wrong host.Fix:
  1. Ensure the depends_on health check is present so Riven waits for PostgreSQL to be ready: 
    depends_on:
  riven-db:
    condition: service_healthy
  2. Verify the healthcheck block is defined on the riven-db service: 
    healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  interval: 10s
  timeout: 5s
  retries: 5
  3. Check the connection URL. The host must be the Docker service name, not localhost: 
    # Correct — "riven-db" is the compose service name
RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:CHANGEME@riven-db:5432/riven"

# Wrong — localhost inside the Riven container is the Riven container itself
RIVEN_SETTING__databaseUrl="postgres+psycopg2://riven:CHANGEME@localhost:5432/riven"
Symptoms: Riven logs contain migration failed, relation already exists, or similar SQL errors shortly after startup.Cause: Running migrations against an incompatible schema state, usually after a rollback to an older image or a partial migration from a crashed startup.Fix:
  1. Check the full migration error: 
    docker compose logs riven | grep -i migration
  2. Ensure you are running the latest image: 
    docker compose pull
docker compose up -d
  3. If the database schema is corrupted beyond repair and you have a backup, restore from it: 
    # Stop everything
docker compose down

# Drop the volume (data loss — only do this if you have a backup)
docker volume rm $(docker compose config --volumes | grep postgres)

# Restore from backup
docker compose up -d postgres
gunzip -c riven-backup.sql.gz \
  | docker compose exec -T postgres psql -U riven riven

# Start riven
docker compose up -d riven

​
API Issues

Symptoms: curl http://<host-ip>:3000 gets Connection refused. The port is published in docker-compose.yml and docker compose ps shows the container as healthy. A reverse proxy (Traefik, Nginx) also fails to connect.Cause: RIVEN_SETTING__gqlHost defaults to localhost, which binds the GraphQL server to the loopback interface inside the container. Publishing the port to the Docker host has no effect because the server is not listening on the interface Docker bridges traffic to.Fix: Bind the server to all interfaces:
RIVEN_SETTING__gqlHost="0.0.0.0"
Restart the container after adding this variable:
docker compose up -d riven
Verify the fix:
curl -X POST http://localhost:3000 \
  -H 'content-type: application/json' \
  -d '{"query":"{ __typename }"}'
# Expected: {"data":{"__typename":"Query"}}
Symptoms: Most requests succeed but occasional requests time out or return HTTP 503.Cause: Usually a plugin or scraping worker that is blocking the event loop during a long-running operation, or Redis being slow under memory pressure.Fix: Check Redis memory usage and Riven logs for slow operations:
docker compose exec redis redis-cli info memory | grep used_memory_human
docker compose logs riven | grep -i "slow\|timeout\|warn"
Consider increasing shutdownTimeoutSeconds if you see timeout warnings during restarts.

​
Plugin Issues

Symptoms: Riven starts without errors but a plugin shows no activity in logs. No scraping or requests are processed by that plugin.Cause: Usually a validation error in the plugin’s settings that prevented it from registering, or the plugin name is misspelled in enabledPlugins.Fix: Check the startup logs for plugin-related validation errors:
docker compose logs riven | grep -i "plugin\|validation\|error"
Common causes:
  • Plugin name is not in RIVEN_SETTING__enabledPlugins (names are case-sensitive)
  • A required API key environment variable is not set or is empty
  • An API key has expired or has insufficient permissions
  • The target service (Seerr, Plex, etc.) is not reachable from inside the container
Symptoms: Logs show API token is not set, apiKey is required, or a Zod validation error for a plugin setting.Cause: The RIVEN_PLUGIN_SETTING__ variable for that plugin’s API key is not set, is set to an empty string, or has a typo in the variable name.Fix: Verify the variable name format and that the value is non-empty in your .env file:
# Correct format
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey="your-key-here"

# Common mistakes:
# 1. Wrong plugin name casing — must be uppercase
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_tmdb__apiKey="..."   # WRONG

# 2. Missing quotes around values with special characters
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey=abc@123  # WRONG

# 3. Extra whitespace around the equals sign
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey = "..."  # WRONG

# 4. Variable set but empty
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TMDB__apiKey=""       # WRONG
After fixing the .env file, recreate the container:
docker compose up -d riven

​
Redis Issues

Symptoms: Riven logs show ECONNREFUSED pointing at the Redis host, or docker compose ps shows the Redis container as unhealthy.Cause: Redis is not running, crashed on startup, or the redisUrl points to the wrong host/port.Fix:
  1. Check the Redis container status and logs: 
    docker compose ps redis
docker compose logs redis
  2. Verify the Redis URL uses the Docker service name: 
    # Correct — "riven-cache" is the compose service name
RIVEN_SETTING__redisUrl="redis://riven-cache:6379"
  3. Test the Redis connection from the Riven container: 
    docker compose exec riven sh -c 'redis-cli -u $RIVEN_SETTING__redisUrl ping'
# Expected: PONG
  4. Ensure the Redis depends_on health check is configured: 
    depends_on:
  riven-cache:
    condition: service_healthy

​
Media Server Issues

Symptoms: Riven reports items as downloaded and indexed, but they do not appear in Plex or Jellyfin.Cause: Usually one of three things — the VFS is not mounted correctly, the media server volume uses the wrong propagation flag, or the library path in the plugin settings points to the wrong path.Fix:
  1. Confirm the VFS is mounted and contains files: 
    ls /mnt/riven
# Should list media directories
  2. Confirm the media server’s Docker volume mount uses rslave: 
    volumes:
  - ${HOST_VFS_MOUNT_PATH}:/mount:rslave
    Not rshared, not plain ro — it must be rslave so the media server receives mount propagation events from Riven’s container.
  3. Trigger a manual library scan in your media server dashboard.
  4. Ensure the plugin’s library path setting matches the path as the media server container sees it. If the volume maps the host’s /mnt/riven to /mount inside the media server container, the plugin setting must use /mount: 
    RIVEN_PLUGIN_SETTING__REPO_PLUGIN_PLEX__plexLibraryPath="/mount"
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_JELLYFIN__jellyfinLibraryPath="/mount"
Symptoms: Jellyfin or Plex scans on startup but finds an empty directory and marks the library as unavailable. Files added later are not picked up automatically.Cause: The media server container started before Riven finished mounting the VFS.Fix: Add a depends_on directive to the media server service:
jellyfin:
  # ...
  depends_on:
    riven:
      condition: service_started
Then trigger a manual rescan from the media server dashboard after everything is running:
  • Plex: Libraries → (three-dot menu) → Scan Library Files
  • Jellyfin: Dashboard → Libraries → (kebab menu) → Scan All Libraries

​
Docker Issues

Symptoms: docker compose ps shows the Riven container repeatedly restarting. docker compose logs riven shows it starting and immediately exiting.Cause: A fatal startup error — typically a missing required environment variable, a service dependency that is unreachable, or a file system permission error on the logs or data directories.Fix: Read the last 50 lines of logs to find the exit reason:
docker compose logs --tail=50 riven
Work through the most common causes in order:
Symptom in logsFix
ZodError or validation failedA required RIVEN_SETTING__ variable is missing or invalid
ECONNREFUSED pointing at postgresPostgreSQL is not healthy — check depends_on
ECONNREFUSED pointing at redisRedis is not healthy — check depends_on
ENOENT on /app/logs or /app/dataDirectory does not exist or is not owned by UID 1000
Operation not permitted on FUSEMissing SYS_ADMIN cap or /dev/fuse device
For the directory permission error:
mkdir -p logs data
sudo chown -R 1000:1000 logs data
Symptoms: The container exits with code 137 (SIGKILL) shortly after starting, often during initialization.Cause: The container was killed by the Linux OOM (Out of Memory) killer. Riven’s FUSE VFS and plugin workers can be memory-intensive during the initial library indexing pass.Fix: Check the kernel OOM log:
sudo dmesg | grep -i "oom\|killed process" | tail -20
If OOM is confirmed, either increase the available memory on the host or set a memory limit that is high enough to avoid the kill:
deploy:
  resources:
    limits:
      memory: 2G

​
Getting Help

If none of the above resolves your issue, collect the following before asking for help: 
# Full startup logs
docker compose logs riven > riven-logs.txt

# Container and host info
docker compose ps
docker version
uname -r

# Mount state
findmnt -o TARGET,PROPAGATION /mnt/riven

GitHub Issues

Search existing issues or open a new one. Include your logs and the output of the commands above.

Discord

Join the community Discord for real-time help from other users and the maintainers.

Email

Reach the team directly at contact@riven.tv for non-public issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us