Automated issue resolution for Jellyseerr via Sonarr & Radarr webhooks

⚠️ Work in Progress: Remediarr is under active development. Configuration options, API endpoints, and behavior may change between versions. Please check the changelog and update your configuration when upgrading. Feedback and bug reports are welcome!

Remediarr is a lightweight webhook service that automatically fixes common media issues reported through Jellyseerr. When users report problems like "no audio" or "wrong movie", Remediarr detects the keywords, deletes problematic files, triggers new downloads, and closes the issue—all without manual intervention.

• 🎬 Movie Automation: Handles audio, video, subtitle issues, and wrong movie downloads
• 📺 TV Show Automation: Manages episode-specific problems with season/episode detection
• 🤖 Smart Keyword Detection: Recognizes issue types from user comments
• 💬 User Coaching: Suggests correct keywords when users don't use recognizable terms
• 🔄 Loop Prevention: Avoids processing its own comments and resolved issues
• 📱 Notifications: Optional Gotify and Apprise integration
• 🔐 Security: HMAC signature verification and custom header authentication
• ⚡ Performance: Built with FastAPI for speed and reliability

1. User reports issue in Jellyseerr: "no audio in S02E05"
2. Jellyseerr sends webhook to Remediarr with issue details
3. Remediarr processes the comment, detects "audio" keyword
4. Finds the episode in Sonarr using TVDB ID and season/episode
5. Deletes bad file and triggers new download in Sonarr
6. Comments on issue: "S02E05: replaced file; new download grabbed"
7. Closes the issue automatically

version: '3.8'
services:
  remediarr:
    image: ghcr.io/sbcrumb/remediarr:latest
    container_name: remediarr
    ports:
      - "8189:8189"
    environment:
      # Required - Your service URLs and API keys
      - SONARR_URL=http://sonarr:8989
      - SONARR_API_KEY=your-sonarr-api-key
      - RADARR_URL=http://radarr:7878  
      - RADARR_API_KEY=your-radarr-api-key
      - JELLYSEERR_URL=http://jellyseerr:5055
      - JELLYSEERR_API_KEY=your-jellyseerr-api-key
      
      # Optional - Bazarr subtitle integration
      - BAZARR_URL=http://bazarr:6767
      - BAZARR_API_KEY=your-bazarr-api-key
      
      # Optional - Notifications
      - GOTIFY_URL=https://gotify.example.com
      - GOTIFY_TOKEN=your-gotify-token
      
      # Optional - Security
      - WEBHOOK_SHARED_SECRET=your-shared-secret
      
    restart: unless-stopped

docker run -d \
  --name remediarr \
  -p 8189:8189 \
  -e SONARR_URL=http://sonarr:8989 \
  -e SONARR_API_KEY=your-api-key \
  -e RADARR_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your-api-key \
  -e JELLYSEERR_URL=http://jellyseerr:5055 \
  -e JELLYSEERR_API_KEY=your-api-key \
  -e BAZARR_URL=http://bazarr:6767 \
  -e BAZARR_API_KEY=your-api-key \
  ghcr.io/sbcrumb/remediarr:latest

Configure webhooks in Jellyseerr → Settings → Notifications → Webhooks:

• Webhook URL: http://your-server:8189/webhook/jellyseerr
• Request Method: POST
• Notification Types: Check only "Issue Reported" (other types will cause loops)

{
  "event": "{{event}}",
  "subject": "{{subject}}",
  "message": "{{message}}",
  "media": {
    "media_type": "{{media_type}}",
    "tmdbId": "{{media_tmdbid}}",
    "tvdbId": "{{media_tvdbid}}",
    "seasonNumber": "{{season_number}}",
    "episodeNumber": "{{episode_number}}"
  },
  "issue": {
    "issue_id": "{{issue_id}}",
    "issue_type": "{{issue_type}}",
    "issue_status": "{{issue_status}}",
    "problemSeason": "{{affected_season}}",
    "problemEpisode": "{{affected_episode}}"
  },
  "comment": {
    "comment_message": "{{comment_message}}"
  }
}

Important: Only enable "Issue Reported" notifications to prevent processing loops

Remediarr is configured entirely through environment variables. See the complete configuration guide for all options.

You can customize which keywords trigger each action type:

# TV Show Keywords
TV_AUDIO_KEYWORDS="no audio,no sound,missing audio,audio issue,wrong language"
TV_VIDEO_KEYWORDS="no video,video glitch,black screen,stutter,pixelation"  
TV_SUBTITLE_KEYWORDS="missing subs,no subtitles,bad subtitles,wrong subs"
TV_OTHER_KEYWORDS="buffering,playback error,corrupt file"

# Movie Keywords  
MOVIE_AUDIO_KEYWORDS="no audio,no sound,audio issue,wrong language"
MOVIE_VIDEO_KEYWORDS="no video,video missing,bad video,black screen"
MOVIE_SUBTITLE_KEYWORDS="missing subs,no subtitles,bad subtitles"
MOVIE_OTHER_KEYWORDS="buffering,playback error,corrupt file"
MOVIE_WRONG_KEYWORDS="wrong movie,incorrect movie,not the right movie"

# HMAC signature verification (recommended)
WEBHOOK_SHARED_SECRET="your-secret-key"

# Or custom header authentication
WEBHOOK_HEADER_NAME="X-Custom-Auth"
WEBHOOK_HEADER_VALUE="your-auth-token"

• Audio Issues: "no audio", "missing audio", "wrong language" → Deletes episode file, triggers re-download
• Video Issues: "no video", "black screen", "pixelation" → Deletes episode file, triggers re-download
• Subtitle Issues: "no subtitles", "subs out of sync" → Uses Bazarr (if configured) to search for subtitles, otherwise deletes episode file and triggers re-download
• Other Issues: "buffering", "corrupt file" → Deletes episode file, triggers re-download

• Audio/Video Issues: Same behavior as TV shows
• Subtitle Issues: Uses Bazarr (if configured) to search for subtitles, otherwise deletes movie files and triggers new search
• Wrong Movie: "wrong movie", "incorrect movie" → Deletes all movie files, triggers new search
• Other Issues: "buffering", "corrupt file" → Deletes movie files, triggers new search

When Bazarr is configured (BAZARR_URL and BAZARR_API_KEY set), subtitle issues are handled more intelligently:

• Movies: Searches for new subtitles via Bazarr, deletes existing poor subtitles first
• TV Shows: Triggers subtitle search for the specific episode via Bazarr
• Fallback: If Bazarr is unavailable or fails, falls back to traditional file deletion and re-download

• Faster resolution: Only downloads subtitles, not entire media files
• Provider diversity: Leverages Bazarr's multiple subtitle providers
• Language support: Respects Bazarr's configured languages and preferences
• Bandwidth efficient: Avoids unnecessary media re-downloads for subtitle-only issues

When users don't include recognizable keywords, Remediarr posts helpful suggestions:

User comment: "this doesn't work"
Remediarr response: "Tip for other issues: Include keywords like 'buffering', 'corrupt file', 'playback error' for automatic fixes."

By default, a healthcheck notification is sent on every application startup. This behavior can be disabled by adding the following:

DISABLE_STARTUP_NOTIFICATION=true

GOTIFY_URL=https://gotify.example.com
GOTIFY_TOKEN=AbCdEf123456
GOTIFY_PRIORITY=5

APPRISE_URLS="discord://webhook_id/webhook_token,slack://hook_url"

• GET / - Basic status and version info
• GET /health - Simple health check
• GET /health/detailed - Health check including external services
• POST /webhook/jellyseerr - Main webhook endpoint
• GET /docs - Interactive API documentation

"Missing tvdbId/season/episode" error

• Ensure your Jellyseerr webhook payload includes all the template variables
• Check that the issue was reported with season/episode information

Issues not auto-closing

• Some Jellyseerr versions don't support the close API endpoint
• Disable with JELLYSEERR_CLOSE_ISSUES=false if needed
• Remediarr will still comment when actions are taken

Webhook loops

• Only enable "Issue Reported" in Jellyseerr webhook settings
• Don't enable "Issue Comment" or other event types

Files not found in Sonarr/Radarr

• Verify the content exists in your *arr apps
• Check that TVDB/TMDB IDs match between Jellyseerr and your *arr apps

LOG_LEVEL=DEBUG

This enables detailed logging of webhook processing, keyword matching, and API calls.

git clone https://github.com/sbcrumb/remediarr.git
cd remediarr
cp .env.example .env
# Edit .env with your settings
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8189

docker build -t remediarr:dev .
docker run --rm -p 8189:8189 --env-file .env remediarr:dev

• Latest stable: ghcr.io/sbcrumb/remediarr:latest
• Version tagged: ghcr.io/sbcrumb/remediarr:v1.0.0
• Development: ghcr.io/sbcrumb/remediarr:dev

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests if applicable
5. Commit: git commit -m 'Add feature'
6. Push: git push origin feature-name
7. Open a Pull Request

Please update .env.example if you add new configuration options.

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Check the .env.example file for all configuration options

If Remediarr saves you time managing media issues:

• GitHub Sponsors
• Bitcoin: bc1qjc200yg9mc08uskmeka8zrjddp8lw2j6d8q0kn