Troubleshoot Riven: Logs, Debug, and Common Fixes

When something goes wrong, Riven gives you several tools to diagnose the problem: a live log endpoint, a one-click log uploader, a full debug bundle generator, and health/service check endpoints. This guide walks through each tool, then covers the most common issues you’re likely to encounter and how to fix them.

For real-time help, join the Riven Discord. When reporting a bug, always attach the output of POST /api/v1/debug — it includes logs, a database snapshot, and system information in one step.

Section 1: Getting Logs

View logs in the browser or via API

GET /api/v1/logs returns the current log file as an array of strings (one entry per line). This is useful for quick inspection or piping into jq:

curl http://localhost:8080/api/v1/logs \
  -H "X-API-Key: YOUR_API_KEY" | jq '.logs[]'

Upload logs to a paste service

POST /api/v1/upload_logs reads the active log file and uploads it to paste.c-net.org, then returns a shareable URL. Limits: 50 MB file size, 180-day retention.

curl -X POST http://localhost:8080/api/v1/upload_logs \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "url": "https://paste.c-net.org/AbCdEfGh"
}

Generate a full debug bundle

POST /api/v1/debug does everything in one request: uploads the log file, creates a database backup snapshot, and returns system information. Use this when filing a bug report.

curl -X POST http://localhost:8080/api/v1/debug \
  -H "X-API-Key: YOUR_API_KEY"

Response fields:

Field	Type	Description
`success`	`bool`	`true` if both log upload and DB backup succeeded
`log_url`	`string \| null`	URL of the uploaded log file on paste.c-net.org
`db_backup_filename`	`string \| null`	Filename of the database snapshot saved locally
`system_info`	`object`	Platform, Python version, CPU count, load avg, memory, swap, disk
`errors`	`list[string]`	Any non-fatal errors encountered during bundle generation

Example response:

{
  "success": true,
  "log_url": "https://paste.c-net.org/AbCdEfGh",
  "db_backup_filename": "riven_backup_20250115_203412.sql",
  "system_info": {
    "platform": "Linux-6.8.0-51-generic-x86_64",
    "python_version": "3.12.3",
    "cpu_count": 8,
    "load_avg": [0.45, 0.52, 0.61],
    "memory": "31.26GB",
    "swap": "2.00GB",
    "disk": "931.51GB"
  },
  "errors": []
}

Adjusting log verbosity

The log level is controlled by log_level in the root AppModel. Valid values are TRACE, DEBUG, INFO, WARNING, ERROR, and CRITICAL (default: INFO). Set it to DEBUG for detailed service output, or TRACE for maximum verbosity:

curl -X POST http://localhost:8080/api/v1/settings/set/log_level \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"log_level": "DEBUG"}'

To also log every outgoing HTTP request and response (useful for diagnosing scraper or debrid API issues), enable enable_network_tracing:

curl -X POST http://localhost:8080/api/v1/settings/set/enable_network_tracing \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enable_network_tracing": true}'

enable_network_tracing logs full HTTP request/response bodies. Disable it after debugging — it can produce very large log files and may expose API keys in the log.

Section 2: Common Issues

Items are stuck in the Scraped state

Items enter Scraped when Riven has found a matching torrent and is waiting for the debrid provider to add it. If they never advance to Downloading or Completed:

Check your debrid API key. Go to GET /api/v1/settings/get/downloaders and verify the API key is set and correct. Test it directly against the debrid provider’s API.
Verify your account is premium. Real-Debrid and AllDebrid free accounts cannot add torrents for instant download. Use GET /api/v1/downloader_user_info to check your premium status:
```
curl http://localhost:8080/api/v1/downloader_user_info \
  -H "X-API-Key: YOUR_API_KEY"
```
Look for "premium_status": "premium" in the response. If you see "free", upgrade your debrid account.
Enable DEBUG logging and restart Riven to see the exact error returned by the debrid API.

Plex shows an empty /mount after Riven restarts

This is a mount propagation issue, not a Riven bug. The FUSE filesystem needs to be visible inside the Plex container.Quick checklist:

Host directory has shared or rshared propagation (findmnt -T /path/to/riven/mount -o PROPAGATION).
Plex’s Docker volume uses :rslave,z (not :rshared or no flag at all).
filesystem.mount_path in Riven settings is the container path /mount, not the host path.

See the Plex Setup troubleshooting section for the full step-by-step fix including how to clear a stale FUSE mount.

Services are not initializing

Use GET /api/v1/services to see which services started successfully:

curl http://localhost:8080/api/v1/services \
  -H "X-API-Key: YOUR_API_KEY"

Example response:

{
  "realdebrid": true,
  "plex_updater": false,
  "torrentio": true,
  "overseerr": false
}

Any service showing false failed to initialize. Common causes:

Missing or invalid API key / URL for that service — check its settings key.
Network unreachable — verify Riven can reach the service from inside the container (docker exec riven curl http://plex:32400).
Service not enabled — confirm enabled: true is set for the service.

Enable DEBUG logging and restart Riven to see the initialization error in the logs.

Items never leave the Requested state

Items stay Requested when no scraper finds a matching result:

Confirm at least one scraper is enabled. Check GET /api/v1/services — at least one scraper (e.g. torrentio, comet) must show true.
Check scraper results manually. Enable DEBUG logging, then re-request the item and watch the logs for lines like Torrentio returned 0 results. Zero results from all scrapers means no torrent was found.
Verify scraper connectivity. Some scrapers require an API key (Orionoid, Jackett, Prowlarr). Use enable_network_tracing to inspect the raw HTTP calls and responses.
Check ranking filters. If scrapers return results but items still don’t advance, your RTN ranking settings may be filtering out all candidates. Temporarily lower minimum rank thresholds to verify.

High memory usage

RivenVFS caches file chunks in memory and on disk. Two settings control this:

filesystem.cache_max_size_mb — maximum on-disk cache size in MB. Reduce this if disk usage is too high.
Eviction policy — defaults to LRU (least-recently-used). If you prefer time-based eviction, switch to TTL and configure ttl_seconds.

To reduce memory pressure, lower filesystem.fetch_ahead_chunks (default 4, each chunk is chunk_size_mb, default 32 MB). Setting it to 1 or 2 reduces prefetch while still enabling smooth playback for most streams.

curl -X POST http://localhost:8080/api/v1/settings/set/all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filesystem": {
      "cache_max_size_mb": 2048,
      "fetch_ahead_chunks": 2
    }
  }'

Database connection errors at startup

Riven requires PostgreSQL to be healthy before it starts. In docker-compose.yml, the riven service has a depends_on with condition: service_healthy pointing to riven_postgres.If you see connection errors:

Check the PostgreSQL container is running: docker ps | grep riven-db.
Verify the RIVEN_DATABASE_HOST environment variable matches the compose service name and credentials:
```
RIVEN_DATABASE_HOST=postgresql+psycopg2://postgres:postgres@riven-db/riven
```
Check PostgreSQL logs: docker logs riven-db.
Ensure the pgdata volume path on the host is writable by the PUID/PGID user.

Section 3: Health Checks

Use these endpoints to quickly assess Riven’s state without reading the full log.

Check if Riven has finished initializing

curl http://localhost:8080/api/v1/health \
  -H "X-API-Key: YOUR_API_KEY"

Response when ready:

{ "message": "True" }

Response while still starting up:

{ "message": "False" }

Check which services are running

curl http://localhost:8080/api/v1/services \
  -H "X-API-Key: YOUR_API_KEY"

Returns a flat dictionary of every service key mapped to its initialized status (true / false). Services with false either failed to initialize or are disabled in settings.

Get library statistics

curl http://localhost:8080/api/v1/stats \
  -H "X-API-Key: YOUR_API_KEY"

Key fields in the response:

Field	Description
`total_items`	Total media items tracked in the database
`total_movies`	Count of movie items
`total_shows`	Count of show items
`total_episodes`	Count of episode items
`total_symlinks`	Number of items with active filesystem entries
`incomplete_items`	Count of items not yet in the `Completed` state
`states`	Breakdown of item counts by state
`activity`	Daily counts of items requested (ISO date → count)

The states map is especially useful: if you see a large number of items stuck in Scraping or Requested, cross-reference with the common issues above.

{
  "total_items": 1523,
  "total_movies": 412,
  "total_shows": 89,
  "total_seasons": 634,
  "total_episodes": 988,
  "total_symlinks": 1400,
  "incomplete_items": 23,
  "states": {
    "Requested": 5,
    "Scraping": 3,
    "Scraped": 2,
    "Downloading": 4,
    "Symlinked": 9,
    "Completed": 1500
  }
}

Getting Started

Configuration

Core Concepts

Guides

Troubleshoot Riven: Logs, Debug, and Common Fixes

Section 1: Getting Logs

View logs in the browser or via API

Upload logs to a paste service

Generate a full debug bundle

Adjusting log verbosity

Section 2: Common Issues

Section 3: Health Checks

Check if Riven has finished initializing

Check which services are running

Get library statistics

Build docs developers (and LLMs) love

Getting Started

Configuration

Core Concepts

Guides

Documentation Index

​Section 1: Getting Logs

​View logs in the browser or via API

​Upload logs to a paste service

​Generate a full debug bundle

​Adjusting log verbosity

​Section 2: Common Issues

​Section 3: Health Checks

​Check if Riven has finished initializing

​Check which services are running

​Get library statistics

Build docs developers (and LLMs) love

Section 1: Getting Logs

View logs in the browser or via API

Upload logs to a paste service

Generate a full debug bundle

Adjusting log verbosity

Section 2: Common Issues

Section 3: Health Checks

Check if Riven has finished initializing

Check which services are running

Get library statistics