Configuration Editor¶

The Configuration Editor provides a user-friendly interface for managing qBitrr's configuration through the WebUI. All changes are saved to the config.toml file and can trigger live reloads of affected components without requiring a full application restart.

Contents¶

• Overview
• Accessing the Configuration Editor
• Configuration Structure
• Field Types and Widgets
• Validation System
• Save Behavior and Live Reload
• Modal State Persistence
• Dirty State Tracking
• Keyboard Shortcuts
• Tooltips and Descriptions
• API Endpoints
• Common Workflows
• Troubleshooting
• Best Practices
• Related Pages
• See Also

Overview¶

The Configuration Editor replaces manual TOML editing with a structured form interface featuring:

• Organized Sections: Core settings, WebUI, qBittorrent, and per-instance Arr configurations
• Live Validation: Real-time field validation with helpful error messages
• Torrent Handling Summary: When configuring an Arr or qBittorrent instance, a live "How torrents are handled" summary is shown at the top of the modal, describing torrent rules, stalled handling, trackers, seeding, and HnR based on current form values (updates as you edit, before saving).
• Intelligent Reload: Automatic detection of which components need reloading after save
• Visual Feedback: Dirty state tracking, save confirmation, and unsaved changes warnings
• Theme Support: Live theme switching without page reload

Accessing the Configuration Editor¶

Navigate to the Config page via the WebUI sidebar:

http://<host>:6969/ui → Config

Authentication: If WebUI.Token is set, you must authenticate before accessing this page (Bearer token in Authorization header or cookie).

Configuration Structure¶

Core Configuration Sections¶

The editor is organized into three primary sections accessible via summary cards:

1. Settings¶

Core application configuration including logging, disk space management, loop timers, and auto-update settings.

Key Fields:

• Console Level: Log verbosity (CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, TRACE)
• Logging: Enable writing logs to files (~/logs/ or /config/logs)
• Completed Download Folder: Path where qBit completes downloads (must match Arr's path)
• Free Space: Desired free space threshold (e.g., 50G, -1 to disable)
• Free Space Folder: Directory to monitor for free space checks
• Auto Pause/Resume: Automatically pause torrents when disk space is low
• No Internet Sleep Timer (s): Delay before retrying when connectivity is lost
• Loop Sleep Timer (s): Interval between torrent processing passes
• Search Loop Delay (s): Delay between automated search requests
• Failed Category: qBit category for marking failed torrents
• Recheck Category: qBit category triggering force recheck
• Tagless: Enable operation without relying on Arr tags
• Ignore Torrents Younger Than (s): Grace period for new torrents before evaluation
• Ping URLs: Comma-separated hostnames for connectivity checks (e.g., one.one.one.one, dns.google.com)
• FFprobe Auto Update: Automatically download/update bundled ffprobe binary
• Auto Update Enabled: Enable background auto-update worker
• Auto Update Cron: Cron expression for update checks (default: 0 3 * * 0 = Sundays at 3 AM)

Example:

[Settings]
ConsoleLevel = "INFO"
Logging = true
CompletedDownloadFolder = "/mnt/downloads"
FreeSpace = "100G"
FreeSpaceFolder = "/mnt/downloads"
AutoPauseResume = true
NoInternetSleepTimer = 300
LoopSleepTimer = 30
SearchLoopDelay = 60
FailedCategory = "failed"
RecheckCategory = "recheck"
Tagless = false
IgnoreTorrentsYoungerThan = 600
PingURLS = ["one.one.one.one", "dns.google.com"]
FFprobeAutoUpdate = true
AutoUpdateEnabled = true
AutoUpdateCron = "0 3 * * 0"
AutoUpdateChannel = "latest"

Validation:

• CompletedDownloadFolder must not be empty or CHANGE_ME
• FreeSpace must be -1 or a number with optional suffix (K, M, G, T, P)
• FreeSpaceFolder required when FreeSpace != "-1"
• All timer fields must be non-negative numbers
• AutoUpdateCron must contain 5 or 6 space-separated fields
• AutoUpdateChannel must be one of latest, stable, nightly

2. Web Settings¶

WebUI server configuration including host, port, token, theme, and view preferences.

Key Fields:

• WebUI Host: Bind address (default: 0.0.0.0 for all interfaces)
• WebUI Port: Port number (default: 6969, range: 1-65535)
• WebUI Token: Optional bearer token for API/UI authentication (auto-generated if empty)
• Live: Enable live updates for Arr catalogs and the qBittorrent overview (also available as the app-bar Live switch)
• Theme: Visual theme (Light or Dark) — changes apply immediately
• View Density: List density (Comfortable or Compact) — applied on next load

Sonarr/Lidarr browse always uses rows + detail modals (Sonarr: series→season→episode; Lidarr: artist→album→track). Flat episode/album browse lists are permanently gone — there is no View Density or config toggle to restore them.

Example:

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = "abc123def456..."
LiveArr = false
Theme = "Dark"
ViewDensity = "Comfortable"

Validation:

• Host must not be empty
• Port must be between 1 and 65535
• Token accepts any string (empty = no authentication)
• ViewDensity must be Comfortable or Compact

Special Behavior:

• Theme: Changes apply immediately via JavaScript (no save required)
• ViewDensity: Persisted to config; applied when the page is loaded
• Host/Port: Trigger a Waitress rebind (close prior server, bind new host/port)
• Token / UrlBase: Soft-apply in-process without rebinding the listen socket

3. qBit¶

qBittorrent connection details and qBit-managed categories.

Key Fields:

• Disabled: Skip this qBit instance without removing its config (not global headless; omit all [qBit] sections for search-only)
• Host: qBittorrent WebUI host or IP address
• Port: qBittorrent WebUI port (default: 8080)
• UserName: qBittorrent WebUI username (optional if auth bypassed)
• Password: qBittorrent WebUI password (optional if auth bypassed)
• Managed Categories: Tag-based input for categories managed directly by qBit (independent of Arr instances)
• Match subcategories: When enabled, each managed category is treated as a prefix for qBittorrent hierarchical paths (seed matches seed/foo). When disabled (default), only an exact category string matches — use full paths such as parent/child. See qBittorrent configuration.

Managed Categories:

This field allows qBittorrent to manage categories with custom seeding settings, independent of Radarr/Sonarr/Lidarr. Use this for torrents not managed by Arr instances (e.g., manually added torrents, private tracker downloads).

• Tag Input UI: Add categories by typing and pressing Enter or comma
• Visual Tags: Categories display as removable chips/tags
• Quick Removal: Click × on any tag to remove it
• Category validation: Save is blocked if an Arr-managed Category equals any qBit ManagedCategories entry (after normalising slashes). Backslashes in category strings are rejected (qBittorrent uses / only).
• Overlap hints: If one configured path is a parent of another (e.g. seed and seed/tleech), a warning appears in the Arr and qBit instance modals — overlapping paths are allowed but exact API filtering applies unless Match subcategories is on.

Example:

[qBit]
Disabled = false
Host = "localhost"
Port = 8080
UserName = "admin"
Password = "adminpass"
ManagedCategories = ["downloads", "private-tracker", "manual"]
MatchSubcategories = false

Validation:

• Host must not be empty
• Port must be between 1 and 65535
• Exact conflict: ManagedCategories cannot contain the same normalised string as any managed Arr instance Category (matches qBitrr startup rules)
• Category strings must not contain \ (use / for hierarchy)

Arr Instance Configuration¶

Each Radarr, Sonarr, or Lidarr instance is configured independently via dedicated modal dialogs.

Instance Management¶

Adding Instances:

1. Click Add Instance button under "Radarr Instances" or "Sonarr Instances"
2. New instance created with default name (e.g., Radarr-1, Sonarr-2)
3. Instance opens automatically for configuration

Deleting Instances:

1. Click Delete button on instance card
2. Confirm deletion (cannot be undone)
3. Instance removed from config and UI

Renaming Instances:

1. Open instance modal
2. Edit Display Name field
3. Press Enter or blur field to apply
4. Instance key updated in config (e.g., Radarr-1 → Radarr-4K)
5. Automatic Cleanup: Old section and all subsections are automatically removed when you save

Important: The system now explicitly tracks renamed instances to ensure complete cleanup: - All old configuration keys are marked for deletion - Subsections (EntrySearch, Torrent, SeedingMode, Trackers) are automatically removed - No orphaned config sections remain after rename

General Settings¶

Key Fields:

• Display Name: Friendly name for this instance (also used as config key)
• Managed: Toggle whether qBitrr actively manages this instance
• URI: Arr instance URL (e.g., http://localhost:7878)
• API Key: Arr API key from Settings → General → Security
• Category: qBittorrent category applied by this Arr instance (full path when using subcategories, e.g. seed/movies)
• Match subcategories (override): Optional. When set to true or false, overrides the [qBit] / [qBit-*] Match subcategories value for this Arr only; leave unset to inherit the qBit instance default.
• Re-search: Re-run searches for failed torrents after qBitrr removes them
• Import Mode: Preferred import mode (Move, Copy, or Auto)
• RSS Sync Timer (min): Interval between RSS sync requests (0 = disabled)
• Refresh Downloads Timer (min): Interval between queue refresh requests (0 = disabled)
• Arr Error Codes To Blocklist: Comma-separated list of Arr error messages triggering blocklist

Example:

[Radarr-4K]
Managed = true
URI = "http://localhost:7878"
APIKey = "abc123..."
Category = "radarr-4k"
ReSearch = true
importMode = "Auto"
RssSyncTimer = 5
RefreshDownloadsTimer = 5
ArrErrorCodesToBlocklist = [
    "Not an upgrade for existing movie file(s)",
    "Not a preferred word upgrade for existing movie file(s)",
    "Unable to determine if file is a sample"
]

Validation:

• URI and APIKey required when Managed = true
• Category must not be empty
• Category must not contain \ (use / for qBittorrent hierarchy)
• Timer fields must be non-negative numbers
• Same exact category cannot appear both as this instance's Category (when managed) and in any [qBit*].ManagedCategories entry

Entry Search Settings¶

Configure automated searching for missing media, quality upgrades, and request integrations.

Search Behavior:

• Search Missing: Search for missing media items
• Also Search Specials (Sonarr only): Include season 0 specials
• Unmonitored: Include unmonitored items in searches
• Do Upgrade Search: Search for improved releases even if file exists
• Quality Unmet Search: Re-search when quality requirements not met
• Custom Format Unmet Search: Re-search when custom format score too low
• Force Minimum Custom Format: Auto-remove torrents not meeting minimum custom format score

Search Configuration:

• Search Limit: Maximum concurrent search tasks (default: 5)
• Search By Year: Order searches by release year
• Search In Reverse: Reverse search order (oldest → newest)
• Search Requests Every (s): Delay between individual search requests (default: 300)
• Search Again On Completion: Restart search loop after exhausting year range

Quality Profiles:

• Use Temp Profile For Missing: Switch to temporary profiles when searching
• Keep Temp Profile: Don't revert to main profile after using temp profile
• Main Quality Profile: Comma-separated primary profile names
• Temp Quality Profile: Comma-separated temporary profile names (paired with main profiles)

Sonarr-Specific:

• Search By Series: Strategy for episode searches (smart, true, false)
  • smart = auto (series search for multiple episodes, episode search for single)
  • true = always search entire series
  • false = always search individual episodes
• Prioritize Today's Releases: Prioritize items released today (RSS-style)

Example:

[Radarr-4K.EntrySearch]
SearchMissing = true
Unmonitored = false
SearchLimit = 5
SearchByYear = true
SearchInReverse = false
SearchRequestsEvery = 300
DoUpgradeSearch = false
QualityUnmetSearch = false
CustomFormatUnmetSearch = false
ForceMinimumCustomFormat = false
SearchAgainOnSearchCompletion = true
UseTempForMissing = false
KeepTempProfile = false
MainQualityProfile = []
TempQualityProfile = []

Validation:

• SearchLimit must be at least 1
• SearchRequestsEvery must be at least 1 second

Request Integration: Ombi¶

Integrate Ombi to automatically search for pending requests.

Key Fields:

• Search Ombi Requests: Enable Ombi integration
• Ombi URI: Ombi server URL (e.g., http://localhost:5000)
• Ombi API Key: Ombi API key
• Approved Only: Only process approved requests
• Is 4K Instance: Treat this config as 4K-specific

Example:

[Radarr-4K.EntrySearch.Ombi]
SearchOmbiRequests = true
OmbiURI = "http://localhost:5000"
OmbiAPIKey = "ombi_key_here"
ApprovedOnly = true
Is4K = true

Request Integration: Overseerr¶

Integrate Overseerr/Jellyseerr to automatically search for pending requests.

Key Fields:

• Search Overseerr Requests: Enable Overseerr integration
• Overseerr URI: Overseerr server URL (e.g., http://localhost:5055)
• Overseerr API Key: Overseerr API key
• Approved Only: Only process approved requests
• Is 4K Instance: Treat this config as 4K-specific

Example:

[Radarr-4K.EntrySearch.Overseerr]
SearchOverseerrRequests = true
OverseerrURI = "http://localhost:5055"
OverseerrAPIKey = "overseerr_key_here"
ApprovedOnly = true
Is4K = true

Torrent Management Settings¶

Configure how qBitrr evaluates and manages torrents.

File Filtering:

• Case Sensitive Matches: Enable case-sensitive regex matching
• Folder Exclusion Regex: Comma-separated regex patterns to exclude folders (e.g., \bextras?\b, \bsamples?\b)
• File Name Exclusion Regex: Comma-separated regex patterns to exclude files (e.g., \bsample\b, \btrailer\b)
• File Extension Allowlist: Comma-separated allowed extensions (e.g., .mp4, .mkv, .srt) — empty = allow all

Torrent Health:

• Auto Delete: Automatically delete unrecognized files
• Ignore Torrents Younger Than (s): Grace period before evaluating torrents (default: 600)
• Maximum ETA (s): Torrents with ETA above this are considered stalled (default: 604800 = 7 days)
• Maximum Deletable Percentage: Upper bound completion % for deletion (0.99 = 99%)
• Do Not Remove Slow: Ignore slow torrents when pruning
• Stalled Delay (min): Minutes to allow stalled torrents before action (-1 = disabled, 0 = infinite)
• Re-search Stalled: Re-run searches for stalled torrents

Tracker Management:

• Remove Dead Trackers: Remove trackers flagged as dead
• Remove Tracker Messages: Comma-separated tracker status messages triggering removal (e.g., skipping tracker announce (unreachable))

Example:

[Radarr-4K.Torrent]
CaseSensitiveMatches = false
FolderExclusionRegex = ["\\bextras?\\b", "\\bsamples?\\b"]
FileNameExclusionRegex = ["\\bsample\\b", "\\btrailer\\b"]
FileExtensionAllowlist = [".mp4", ".mkv", ".sub", ".srt"]
AutoDelete = false
IgnoreTorrentsYoungerThan = 600
MaximumETA = 604800
MaximumDeletablePercentage = 0.99
DoNotRemoveSlow = true
StalledDelay = 15
ReSearchStalled = false
RemoveDeadTrackers = false
RemoveTrackerWithMessage = ["skipping tracker announce (unreachable)", "No such host is known"]

Validation:

• All numeric fields must be non-negative
• MaximumDeletablePercentage must be a decimal between 0 and 1 (e.g. 0.99 = 99%)

Seeding Mode Settings¶

Configure per-instance seeding policies.

Key Fields:

• Download Rate Limit Per Torrent: KB/s download limit (-1 = unlimited). qBitrr converts to bytes/s for qBittorrent.
• Upload Rate Limit Per Torrent: KB/s upload limit (-1 = unlimited). qBitrr converts to bytes/s for qBittorrent.
• Max Upload Ratio: Maximum upload ratio (-1 = unlimited)
• Max Seeding Time (s): Maximum seeding duration (-1 = unlimited)
• Remove Torrent (policy): Removal policy:
  • -1 = do not remove
  • 1 = remove on ratio
  • 2 = remove on time
  • 3 = remove on ratio OR time
  • 4 = remove on ratio AND time

Example:

[Radarr-4K.Torrent.SeedingMode]
DownloadRateLimitPerTorrent = -1
UploadRateLimitPerTorrent = -1
MaxUploadRatio = 2.0
MaxSeedingTime = 604800
RemoveTorrent = 3

Validation:

• All fields must be -1 or greater
• RemoveTorrent must be -1, 1, 2, 3, or 4

Tracker-Specific Settings¶

Define custom per-tracker seeding policies and tagging rules.

Key Fields:

• Name: Tracker name (for display purposes)
• URI: Tracker URL (used for matching)
• Priority: Tracker priority (higher = preferred)
• Maximum ETA (s): Override global ETA limit for this tracker
• Download Rate Limit: Override global download limit
• Upload Rate Limit: Override global upload limit
• Max Upload Ratio: Override global upload ratio
• Max Seeding Time (s): Override global seeding time
• Add Tracker If Missing: Automatically add this tracker to matching torrents
• Remove If Exists: Remove torrents from this tracker
• Super Seed Mode: Enable super seeding for this tracker
• Add Tags: Comma-separated tags to apply to torrents from this tracker

Example:

[[Radarr-4K.Torrent.Trackers]]
Name = "Premium Tracker"
URI = "https://premium.tracker.com/announce"
Priority = 10
MaximumETA = 86400
DownloadRateLimit = -1
UploadRateLimit = -1
MaxUploadRatio = 3.0
MaxSeedingTime = 1209600
AddTrackerIfMissing = false
RemoveIfExists = false
SuperSeedMode = false
AddTags = ["premium"]

Validation:

• Name and URI required
• All numeric fields must be non-negative or -1

UI Features:

• Add Tracker: Click "+ Add Tracker" to create new tracker config
• Delete Tracker: Click trash icon on tracker card to remove
• Collapsible Cards: Each tracker is a collapsible card showing name in header

Field Types and Widgets¶

Text Input¶

Standard text field for strings.

<input type="text" value="..." />

Number Input¶

Numeric field with spinner controls.

<input type="number" value="42" />

Duration Input¶

Time fields use a number input plus unit dropdown (s, m, h, d, w, M) instead of raw seconds or minutes. When you change a duration and save, the config may store it as a suffixed string (e.g. MaxSeedingTime = "1w", StalledDelay = "60m") for readability; the backend accepts both integers and suffixed strings. Fractional values are preserved at the field's native seconds-or-minutes precision instead of being rounded to a whole selected unit. Disabled values (-1) show an empty field with a Disabled placeholder; use Use disabled or clear the field and blur to set disabled again.

Checkbox¶

Toggle boolean values.

<input type="checkbox" checked />

Password¶

Masked text field (shows bullets).

<input type="password" value="***" />

Secure Field¶

Special field for API keys and tokens with:

• Visibility Toggle: Show/hide value
• Refresh Button: Generate new random key (32-character hex)

Example: WebUI.Token, Arr.APIKey, Ombi.OmbiAPIKey

Select Dropdown¶

Dropdown for predefined options (using react-select with theme-aware styling).

Examples:

• Console Level: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, TRACE
• Import Mode: Move, Copy, Auto
• Theme: Light, Dark
• Search By Series (Sonarr): smart, true, false

Tag Input¶

Interactive chip/tag-based input for managing arrays of strings.

Features:

• Visual Tags: Values display as styled chips with × remove buttons
• Quick Add: Type and press Enter or comma to add new tags
• Backspace Delete: Press Backspace on empty input to remove last tag
• Duplicate Prevention: Automatically prevents adding duplicate values
• Theme Support: Tags styled according to current theme

Examples:

• Managed Categories (qBit): ["downloads", "private-tracker", "manual"]
• Arr Error Codes To Blocklist: ["Not an upgrade", "Unable to determine if sample"]

Usage: 1. Click in the input field 2. Type a category name (e.g., downloads) 3. Press Enter or comma to add the tag 4. Click × on any tag to remove it 5. Press Backspace with empty input to remove the last tag

Validation System¶

The form and the server save-gate (POST /api/config → validate_config_update) enforce the same comment-derived constraints from the config field registry / config.example.toml (closed enums, FreeSpace format, HnR 0–100, port ranges, CHANGE_ME placeholders, UrlBase shape, and AuthDisabled + public-bind acknowledgment). Hand-edited TOML is still soft-checked at process startup (logged warnings only); invalid values are blocked when saving through the WebUI or API.

Real-Time Validation¶

The editor validates fields on change and before save, displaying inline error messages.

Validation Types:

1. Type Validation: Ensure value matches expected type (string, number, boolean)
2. Range Validation: Check numeric fields fall within valid ranges (e.g., port 1-65535, HnR percent 0–100)
3. Conditional Validation: Some fields required only when related fields are set
4. Custom Validation: Field-specific logic (e.g., cron expression format, FreeSpace units)
5. Cross-section categories: Arr Category vs qBit ManagedCategories exact duplicates block save; backslashes in category fields block save; parent/child path overlaps show non-blocking warnings in Arr/qBit modals (see qBittorrent → Subcategories)

Common Validation Rules¶

Error Display¶

Validation errors are displayed:

1. Inline: Affected fields are highlighted and show the error message under the control (sections with errors auto-expand)
2. Footer note: Modal footer lists all current blocking issues while editing
3. On Save: Error toast lists every invalid path and message (client-side and server-side validation)

Example Error:

Please resolve the following issues:
WebUI.Port: WebUI Port must be between 1 and 65535.
Radarr-4K.URI: URI must be set to a valid URL when the instance is managed.

Save Behavior and Live Reload¶

Modal-only Save¶

Saving is done from each configure modal (and per-instance Save on Arr/qBit cards). There is no page-footer Save + Live Reload control — core blocks (Settings, Web Settings, Authentication) and each Arr/qBit instance are saved from their own modal.

• Per-instance / modal Save validates only that section (skipped when Arr Managed = false or qBit Disabled = true)
• Save is disabled while the open section has validation errors; qBit/Arr live reload runs only after a successful Save
• Closing a modal without Save discards unsaved edits for that modal
• The API also rejects invalid updates with HTTP 400 (no persist, no reload) so clients cannot bypass the WebUI gate

Save Process¶

When you click Save in a configure modal (or on an instance card):

1. Client-Side Validation: Only the target section is validated; save blocked if errors exist
2. Change Detection: Compares current form state vs. original config
3. Diff Calculation: Generates minimal change set (only modified fields for that section)
4. API Request: POST /api/config with {"changes": {...}}
5. Server-Side Validation: Backend validates and persists to config.toml
6. Reload Detection: Server classifies keys via qBitrr/config_reload_policy.py
7. Reload Execution: Server applies the lightest safe reload
8. Response: Success message with reload type

Reload Strategies¶

The backend uses intelligent reload detection to minimize disruption (aligned with Config file → Live config reload and API → Update Configuration):

API Response¶

{
  "status": "ok",
  "configReloaded": true,
  "reloadType": "single_arr",
  "affectedInstances": ["Radarr-4K"]
}

Response Headers:

X-Config-Reloaded: true
Cache-Control: no-cache, no-store, must-revalidate

Protected Keys¶

The following keys cannot be modified via the WebUI:

• Settings.ConfigVersion (managed automatically by migration system)

Attempts to modify protected keys return 403 Forbidden.

Modal State Persistence¶

Configuration modals preserve their state while you work in the Config tab:

Persistent State:

• Open Modals: Remain open while you stay on the Config tab
• Entered Data: All field values are preserved until you save or reload config
• Unsaved Changes: Prompted when leaving Config via another tab if changes exist

Interaction Safety:

• Modals ignore accidental clicks after text selection (e.g. releasing the mouse over Close after highlighting a field)
• Escape closes modals unless focus is in an input, textarea, or select
• Instance modals render as a full-screen overlay so they are not obscured by page navigation

Note: Switching to another WebUI tab (Processes, Logs, etc.) unmounts the Config page and closes modals. You are prompted to confirm if unsaved changes exist.

Dirty State Tracking¶

The editor tracks whether unsaved changes exist:

Indicators:

• Save Button State: Enabled when changes exist, disabled when clean
• Browser Warning: "You have unsaved changes" prompt if navigating away
• Visual Feedback: No explicit "unsaved changes" banner (rely on button state)

Change Detection:

• Compares flattened current state vs. original state
• Detects added, modified, and removed keys
• Array fields compared via JSON serialization

Escape Routes:

• Save: Apply changes and clear dirty state
• Reload: Refresh page to discard changes (browser prompts confirmation)

Keyboard Shortcuts¶

Global¶

• Escape: Close any open modal

Text Fields¶

• Enter: Commit changes (on rename fields)
• Escape: Revert to original value (on rename fields)

Tooltips and Descriptions¶

Field Tooltips¶

Hover over field labels to see tooltips with detailed descriptions (defined in webui/src/config/tooltips.ts).

Example:

"Settings.FreeSpace": "Desired free space threshold (use K, M, G, T suffix). Set to -1 to disable the free space guard."

Field Descriptions¶

Below each field is a short auto-generated description:

• Checkbox: "Enable or disable {label}."
• Other: "Set the {label} value."

For complex fields, custom descriptions override the default (e.g., EntrySearch.SearchBySeries shows strategy options).

API Endpoints¶

Get Configuration¶

Fetch current configuration from disk.

Endpoint: GET /api/config

Authentication: Required (Bearer token)

Response:

{
  "Settings": {
    "ConsoleLevel": "INFO",
    "Logging": true,
    "CompletedDownloadFolder": "/mnt/downloads",
    ...
  },
  "WebUI": {
    "Host": "0.0.0.0",
    "Port": 6969,
    ...
  },
  "qBit": {
    "Host": "localhost",
    "Port": 8080,
    ...
  },
  "Radarr-4K": {
    "Managed": true,
    "URI": "http://localhost:7878",
    ...
  },
  ...
}

Error:

{
  "error": "Failed to load configuration"
}

Update Configuration¶

Apply changes to configuration and trigger reload.

Endpoint: POST /api/config

Authentication: Required (Bearer token)

Request Body:

{
  "changes": {
    "Settings.LoopSleepTimer": 60,
    "Radarr-4K.EntrySearch.SearchLimit": 10,
    "WebUI.Theme": "Dark"
  }
}

Dotted Key Format: Use dot notation for nested keys (e.g., Radarr-4K.Torrent.AutoDelete).

Deletion: Set value to null to delete key (e.g., {"WebUI.Token": null}).

Response:

{
  "status": "ok",
  "configReloaded": true,
  "reloadType": "multi_arr",
  "affectedInstances": ["Radarr-4K"]
}

Validation Error:

{
  "error": "Please resolve the following issues:\nWebUI.Port: WebUI Port must be between 1 and 65535."
}

Protected Key Error:

{
  "error": "Cannot modify protected configuration key: Settings.ConfigVersion"
}

Test Arr Connection¶

Test connection to Arr instance without saving configuration.

Endpoint: POST /api/arr/test-connection

Authentication: Required (Bearer token)

Request Body:

{
  "arrType": "radarr",
  "uri": "http://localhost:7878",
  "apiKey": "abc123..."
}

Response (Success):

{
  "success": true,
  "version": "4.3.2.6857",
  "qualityProfiles": [
    {"id": 1, "name": "HD-1080p"},
    {"id": 4, "name": "Ultra-HD"}
  ]
}

Response (Failure):

{
  "success": false,
  "message": "Connection refused"
}

Common Workflows¶

Adding a New Radarr Instance¶

1. Navigate to Config page
2. Scroll to Radarr Instances section
3. Click Add Instance
4. Instance modal opens with default name (Radarr-1, Radarr-2, etc.)
5. Configure fields:
   • Rename instance (e.g., Radarr-4K)
   • Set URI (e.g., http://localhost:7878)
   • Set API Key (copy from Radarr Settings → General → Security)
   • Set Category (e.g., radarr-4k)
6. Configure optional settings (Entry Search, Torrent, Seeding, Trackers)
7. Click Save in the modal
8. New Radarr instance starts managing downloads

Changing Global Loop Timer¶

1. Navigate to Config page
2. Click Configure on Settings card
3. Change Loop Sleep Timer (s) (e.g., 30 → 60)
4. Click Save in the modal
5. Backend applies a live reload (no worker restart)

Updating WebUI Port¶

1. Navigate to Config page
2. Click Configure on Web Settings card
3. Change WebUI Port (e.g., 6969 → 8080)
4. Click Save in the modal
5. WebUI server restarts on new port
6. Browser redirects to http://<host>:8080/ui

Switching Theme¶

1. Navigate to Config page
2. Click Configure on Web Settings card
3. Change Theme dropdown (Light / Dark)
4. Theme applies immediately (no save required)
5. Optional: Click Save in the modal to persist theme preference
6. Close modal

Configuring Ombi Integration¶

1. Open Radarr/Sonarr instance modal
2. Scroll to Request Integration: Ombi section
3. Enable Search Ombi Requests
4. Set Ombi URI (e.g., http://localhost:5000)
5. Set Ombi API Key (copy from Ombi Settings → API)
6. Enable Approved Only (recommended)
7. Set Is 4K Instance (if applicable)
8. Click Save in the modal
9. qBitrr begins polling Ombi for pending requests

Adding Custom Tracker Rules¶

1. Open Radarr/Sonarr instance modal
2. Scroll to Trackers section
3. Click Add Tracker
4. New tracker card appears
5. Configure tracker:
   • Name: IPTorrents
   • URI: https://iptorrents.com/announce.php
   • Priority: 10
   • Max Upload Ratio: 2.0
   • Add Tags: ipt
6. Repeat for additional trackers
7. Click Save in the modal
8. Tracker rules apply to matching torrents

Troubleshooting¶

Config Not Loading¶

Symptom: Loading spinner never disappears

Causes:

1. Invalid TOML Syntax: Config file has syntax errors
2. Permission Issues: qBitrr cannot read config.toml
3. WebUI Token: Token mismatch or missing authentication

Solutions:

• Check browser console for API errors
• Verify config.toml syntax: toml-lint ~/config/config.toml
• Check file permissions: ls -la ~/config/config.toml
• Regenerate token: Remove WebUI.Token from config, restart qBitrr

Changes Not Saving¶

Symptom: Save button completes but changes not reflected after reload

Causes:

1. Validation Errors: Silent validation failures
2. Write Permissions: qBitrr cannot write to config.toml
3. Config Version Mismatch: Automatic migration overwrites changes

Solutions:

• Check for validation error messages on page
• Verify write permissions: touch ~/config/config.toml && rm ~/config/config.toml
• Check logs for migration warnings: tail -f ~/logs/Main.log

Reload Not Triggering¶

Symptom: Save succeeds but components don't reload

Causes:

1. Wrong Reload Type: Frontend-only changes don't reload backend
2. Instance Not Found: Renamed instance doesn't exist in manager
3. Process Crashed: Arr instance crashed during reload

Solutions:

• Check response JSON for reloadType and affectedInstances
• Verify instance exists: Check Processes page
• Check logs: tail -f ~/logs/Main.log and ~/logs/<ArrName>.log

Modal Won't Close¶

Symptom: Clicking outside modal doesn't close it

Causes:

1. Unsaved Changes: No warning but modal remains open
2. JavaScript Error: React component error prevents close

Solutions:

• Press Escape key to force close
• Check browser console for React errors
• Refresh page to reset state

Validation Errors Won't Clear¶

Symptom: Field shows error even after correcting value

Causes:

1. Dependent Fields: Another field still invalid
2. Cache Issue: React state not updating
3. Conditional Validation: Related field triggers validation

Solutions:

• Review all error messages (may be multiple)
• Refresh page to reset validation state
• Check related fields (e.g., FreeSpace → FreeSpaceFolder)

Port Change Breaks Connection¶

Symptom: After changing WebUI.Port, cannot access WebUI

Causes:

1. Port Already In Use: Another service using target port
2. Firewall Blocking: Firewall blocks new port
3. WebUI Restart Failed: Server crashed during restart

Solutions:

• Check logs: tail -f ~/logs/WebUI.log
• Verify port availability: netstat -tulpn | grep <port>
• Edit config manually: nano ~/config/config.toml, revert port
• Restart qBitrr: systemctl restart qbitrr (systemd) or restart Docker container

Best Practices¶

1. Test Arr Connections: Use /api/arr/test-connection endpoint (future feature) before saving
2. Incremental Changes: Make small changes and test before bulk updates
3. Backup Config: Keep a backup copy of config.toml before major changes
4. Monitor Logs: Watch logs during/after config changes to catch issues
5. Avoid Direct Edits: Use WebUI instead of manual TOML editing (prevents syntax errors)
6. Theme Changes: Theme is the only setting that applies without save
7. Global vs. Instance: Understand which changes trigger full reload vs. instance reload
8. Secure Fields: Use refresh button to generate strong random keys
9. Tracker Priorities: Higher priority trackers preferred when multiple matches exist
10. Validation First: Fix all validation errors before attempting save

Related Pages¶

• Configuration File Reference – Manual TOML editing guide
• Environment Variables – Environment-based configuration
• Quality Profiles – Setting up quality profiles
• Processes Page – Monitor Arr instance health
• Logs Page – View configuration reload logs

See Also¶

• WebUI Overview – Introduction to the WebUI
• Arr Views – Browse Radarr/Sonarr/Lidarr libraries
• First Run Guide – Initial configuration walkthrough
• Migration Guide – Upgrading from older configs