A configuration change in Recyclarr can affect quality profiles, custom formats, scores, quality definitions, and other settings managed in Sonarr or Radarr. Testing those changes before synchronization provides a safer way to identify configuration errors and confirm that the intended settings will be applied.
Recyclarr includes a preview mode that allows you to run the synchronization process without actually modifying the target Sonarr or Radarr instance. The --preview option allows Recyclarr to retrieve the current application configuration and determine what would change, while preventing write operations that would modify the server.
This makes preview mode particularly useful when creating a new configuration, changing custom format scores, modifying quality profiles, managing multiple instances, or troubleshooting unexpected synchronization results.
Use Recyclarr Preview Mode
The primary method for testing a Recyclarr configuration is the --preview option:
recyclarr sync --preview
This runs the synchronization process in preview mode rather than applying the proposed changes.
Recyclarr can still communicate with Sonarr or Radarr to retrieve information required for the synchronization process. The important difference is that configuration changes are not written back to the target application.
Review the resulting output carefully before performing a normal synchronization.
Test Sonarr Separately
A configuration containing both Sonarr and Radarr settings does not have to be tested as a single operation.
To preview Sonarr synchronization:
recyclarr sync sonarr --preview
This is useful when you have made changes specifically to Sonarr quality profiles, custom formats, or related settings.
Testing Sonarr independently also reduces the amount of output you need to review when troubleshooting a larger configuration.
Test Radarr Separately
Radarr can be tested in the same way:
recyclarr sync radarr --preview
This allows you to review the proposed Radarr changes without applying them.
A service-specific preview is particularly useful when you are modifying movie-related custom formats, quality profiles, or scores while leaving your Sonarr configuration unchanged.
Preview a Specific Configuration File
The --config option can be used when you want to test a particular configuration file.
For example:
recyclarr sync --config ./recyclarr.yml --preview
This is useful when several configuration files exist or when you are testing a new configuration separately from your existing setup.
Recyclarr also supports specifying multiple configuration files when your setup is organized that way.
The important point is to verify that the file being tested is the same file you intended to modify.
Test a Specific Instance
Multi-instance environments require additional care because the same Recyclarr installation may manage several Sonarr or Radarr servers.
You can use the instance filter to test a particular configured instance:
recyclarr sync --instance movies --preview
The instance name must correspond to an instance defined in your Recyclarr configuration.
This approach is useful for setups containing separate servers such as a standard Sonarr instance, an anime Sonarr instance, a standard Radarr instance, and a 4K Radarr instance.
Testing each instance independently makes it easier to identify configuration problems without processing every server at once.
Review the Preview Output
Running a preview is only the first part of the testing process. The output should be reviewed before you apply the configuration.
Pay particular attention to changes involving:
- Quality profiles
- Custom format scores
- Custom formats
- Quality definitions
- Media management settings
- Naming configuration
- Profile assignments
If the preview proposes a change you did not intend to make, do not run the normal synchronization yet.
Return to the configuration file, identify the relevant section, make the correction, and run the preview again.
Test Custom Format Score Changes
Preview mode is particularly useful when changing custom format scores.
For example, if a custom format currently has:
score: 100
and you change it to:
score: 250
run:
recyclarr sync --preview
The preview allows you to confirm that Recyclarr recognizes the intended score change before it is synchronized to Sonarr or Radarr.
This is preferable to changing scores manually and then trying to determine why a later synchronization changed them again.
Test Quality Profile Changes
Quality profiles can contain several related settings, making them worth testing before synchronization.
A change may affect custom format scores, quality preferences, upgrade behavior, or other profile-specific configuration.
Preview the relevant service after making the change and verify that the proposed modifications correspond to your intended configuration.
If the preview shows changes to an unexpected profile, check the profile name and instance definition before proceeding.
Test Custom Format Changes
Adding or modifying custom formats should also be tested through preview mode.
This is especially important when a configuration contains several custom formats because a small configuration mistake can result in unexpected changes across multiple profiles.
Confirm that:
- The custom format name is correct.
- The intended instance is being processed.
- The custom format is associated with the correct profile.
- The score is what you expect.
- No unrelated formats are being modified.
A preview gives you an opportunity to catch these problems before they reach the application.
Validate the YAML Configuration
Preview mode should be combined with basic YAML validation.
Recyclarr configurations are YAML files, so indentation and structure matter. A misplaced space, incorrect nesting, or invalid property can prevent the configuration from being processed correctly.
Review recently edited sections carefully and make sure they follow the configuration structure supported by your installed Recyclarr version.
Do not assume that a configuration copied from an older guide will necessarily match the current release.
Use YAML Schema Validation
Recyclarr supports YAML schema validation, which can provide useful feedback while editing the configuration.
A schema declaration can be added near the beginning of the YAML file:
# yaml-language-server: $schema=https://schemas.recyclarr.dev/latest/config-schema.json
Compatible editors can then provide validation and configuration suggestions.
Schema validation and preview mode serve different purposes. Schema validation helps identify structural problems while editing, while preview mode lets you see what Recyclarr intends to do against the current Sonarr or Radarr configuration.
Verify the Sonarr or Radarr Connection
Preview mode still needs to communicate with the target application.
A preview is not an offline YAML test. Recyclarr needs to retrieve information from Sonarr or Radarr to determine the current state and calculate the proposed synchronization.
Check that the configured base_url is correct:
base_url: http://sonarr:8989
and that the corresponding API key is valid.
If Recyclarr cannot reach the application, resolve the connection problem before evaluating the synchronization results.
Check Docker Networking
Docker installations require particular attention to networking.
A common mistake is using localhost when Recyclarr, Sonarr, and Radarr are running in separate containers.
For example:
http://localhost:8989
may refer to the Recyclarr container rather than the Sonarr container.
Depending on the Docker network, the correct address may instead use the Sonarr service name:
http://sonarr:8989
The correct hostname depends on your Docker Compose and network configuration.
A preview command can only test the configuration successfully if Recyclarr can reach the target service from its own execution environment.
Test Recyclarr From the Docker Container
Docker users should ideally test the configuration from the same environment in which Recyclarr normally runs.
With Docker Compose, a preview can be executed using:
docker compose run --rm recyclarr sync radarr --preview
A running Recyclarr container can also be used with:
docker compose exec recyclarr recyclarr sync radarr --preview
This helps identify problems involving container networking, mounted configuration files, permissions, and environment variables.
Use Debug Logging for Troubleshooting
If the normal preview output does not provide enough information, enable more detailed logging.
For example:
recyclarr sync radarr --preview --log debug
Debug output can provide additional information about configuration processing, instance selection, API communication, and synchronization decisions.
Detailed logging is particularly useful when the configuration appears correct but the preview does not produce the expected result.
Confirm the Correct Configuration File
One of the easiest problems to overlook is editing the wrong file.
This can happen when:
- Multiple configuration files exist.
- Docker volumes are mapped incorrectly.
- Recyclarr uses a different configuration directory.
- A scheduled task points to another file.
- A new configuration was created without updating the execution command.
If your changes do not appear in preview mode, verify the configuration path before changing anything else.
Test Multiple Instances Individually
A single Recyclarr setup can manage multiple Sonarr and Radarr instances.
For example, you might have:
Sonarr TV
Sonarr Anime
Radarr Movies
Radarr 4K
Testing all four simultaneously can make troubleshooting unnecessarily difficult.
Instead, preview each relevant instance individually:
recyclarr sync --instance sonarr-tv --preview
Then:
recyclarr sync --instance radarr-4k --preview
Use the actual instance names defined in your configuration.
This approach makes it easier to determine whether an issue is isolated to one server or affects the entire configuration.
Do Not Confuse Preview With a Normal Sync
The difference between the two commands is important.
A normal synchronization applies the configured changes:
recyclarr sync
A preview evaluates the synchronization without applying configuration changes:
recyclarr sync --preview
The preview still communicates with Sonarr or Radarr, but it is intended to prevent the write operations that modify the application’s configuration.
That makes it appropriate for reviewing proposed changes before committing them.
Check the Current Application State
Preview results are based on the current state of the target Sonarr or Radarr instance.
Before judging the output, confirm that the application itself contains the profiles and custom formats you expect.
For example, if your Recyclarr configuration references a particular quality profile, verify that the profile exists on the target server.
The same applies to custom formats and other managed resources.
Testing against the wrong instance can produce confusing results even when the Recyclarr configuration itself is correct.
What If the Preview Shows No Changes?
A preview that produces no configuration changes does not necessarily indicate a problem.
It may simply mean that Sonarr or Radarr already matches the desired Recyclarr configuration.
Check the current application settings and compare them with your YAML configuration.
Also confirm that:
- The correct configuration file is loaded.
- The correct instance is selected.
- The intended quality profile is being managed.
- The custom format is included.
- The changed value is actually different from the current value.
If everything already matches, there may be nothing for Recyclarr to update.
What If the Preview Shows Unexpected Changes?
Do not immediately run a normal synchronization.
Review the specific change and trace it back to the relevant configuration section.
Common causes include:
- Incorrect profile names
- Wrong instance selection
- Unexpected inherited settings
- Incorrect custom format configuration
- An outdated configuration example
- A YAML indentation problem
Correct the configuration and run the preview again.
Repeat this process until the proposed changes match your expectations.
What If the Preview Fails?
The error message should determine the next troubleshooting step.
A YAML or configuration error points toward the configuration structure.
A connection error suggests a URL, Docker networking, firewall, or service availability problem.
An authentication error generally indicates an API key or access issue.
A resource-related error may indicate that a referenced profile or custom format cannot be found or processed.
Avoid making unrelated configuration changes until the reported error has been identified.
Keep a Backup Before Major Changes
Preview mode reduces the risk of accidentally applying an unwanted configuration, but maintaining a backup is still good practice.
Keep a copy of your working Recyclarr configuration before making substantial changes to:
- Quality profiles
- Custom format scores
- Custom formats
- Quality definitions
- Media naming
- Multiple-instance configurations
A backup also makes it easier to compare the previous and updated configurations when troubleshooting.
Test Before a Large Configuration Update
Preview mode becomes particularly valuable when several settings are changing at once.
For example, a larger update might modify quality profiles, custom formats, scores, and quality definitions simultaneously.
Running a normal sync immediately makes it harder to determine which modification produced an unexpected result.
Preview the complete configuration first, review the proposed changes, and correct anything unexpected before applying it.
Recommended Testing Workflow
A practical testing process can be reduced to a few steps:
- Back up the existing Recyclarr configuration.
- Make the required YAML changes.
- Validate the configuration structure.
- Confirm the target URL and API key.
- Run a targeted preview.
- Review the proposed changes.
- Check the affected Sonarr or Radarr instance.
- Correct unexpected results.
- Repeat the preview if necessary.
- Run a normal synchronization only after the output is correct.
For larger installations, test individual instances before processing the entire environment.
Frequently Asked Questions
Does Recyclarr have a dry-run option?
Yes. Recyclarr provides preview mode with the --preview option. It allows the synchronization process to run without applying configuration changes to the target Sonarr or Radarr instance.
What command should I use to test Recyclarr?
Use:
recyclarr sync --preview
You can also target a specific service or instance when testing a larger configuration.
Can I test only Sonarr?
Yes. Use:
recyclarr sync sonarr --preview
This allows you to test the Sonarr configuration without running the Radarr synchronization.
Can I test only Radarr?
Yes. Use:
recyclarr sync radarr --preview
This is useful when you are modifying Radarr-specific settings.
Does preview mode change Sonarr or Radarr?
Preview mode is intended to show the synchronization result without applying configuration changes to the target application.
Can I preview a specific configuration file?
Yes. Use the --config option with the path to the configuration you want to test:
recyclarr sync --config ./recyclarr.yml --preview
Can I test one Recyclarr instance at a time?
Yes. The --instance option can be used to target a specific configured instance.
Does preview mode work with Docker?
Yes. You can run the preview command through Docker Compose or execute it inside the running Recyclarr container.
Why does preview mode fail even though Sonarr works in my browser?
The problem may be related to Docker networking, hostname resolution, firewall rules, or the URL being used by Recyclarr. A URL that works from your desktop is not necessarily reachable from inside the Recyclarr container.
Should I run a preview after changing custom format scores?
Yes. Previewing score changes lets you verify the intended configuration before applying it to Sonarr or Radarr.
Conclusion
Recyclarr’s preview mode provides a practical way to test configuration changes before they are applied to Sonarr or Radarr. Running recyclarr sync --preview allows you to review the synchronization process without committing the proposed configuration changes.
For more precise testing, target Sonarr, Radarr, or an individual instance rather than processing every configured server at once. Validate the YAML structure, confirm the correct configuration file, and verify that Recyclarr can reach the target application.
Previewing changes is especially valuable for custom format scores, quality profiles, multiple instances, and larger configuration updates. Once the preview output matches the intended result, a normal synchronization can be performed with considerably less risk of unexpected configuration changes.