ReadAIrr is a renamed fork of Readarr. Some inherited screenshots, executable names, config keys, API labels, and custom-script environment variables still say Readarr where the current app repo still requires that compatibility name. {.is-info}

Read More on Metadata Issues {.is-info}

#Table of Contents

Table of Contents

#How does ReadAIrr work

{#how-does-readarr-work}

ReadAIrr does not regularly search for book files that are missing or have not met their quality goals. Instead, it fairly frequently queries your indexers and trackers for all the newly posted books, then compares that with its list of books that are missing or need to be upgraded. Any matches are downloaded. This lets ReadAIrr cover a library of any size with just 24-100 queries per day (RSS interval of 15-60 minutes). If you understand this, you will realize that it only covers the future though.
So how do you deal with the present and past? When you're adding a book/author, you will need to set the correct path, profile and monitoring status then use the Start search for missing book checkbox. If the book hasn't been released yet, you do not need to initiate a search.
Put another way, ReadAIrr will only find books that are newly uploaded to your indexers. It will not actively try to find books you want that were uploaded in the past.
If you've already added the book, but now you want to search for it, you have a few choices. You can go to the author's page and use the search button next to the book, which will do a search and then automatically pick one. You can use the Search tab and see all the results, hand picking the one you want. Or you can use the filters of Missing, Wanted, or Cut-off Unmet.
If ReadAIrr has been offline for an extended period of time, ReadAIrr will attempt to page back to find the last release it processed in an attempt to avoid missing a release. As long as your indexer supports paging and it hasn't been too long ReadAIrr will be able to process the releases it would have missed and avoid you needing to perform a search for the missed books.

#Forced Authentication

If ReadAIrr is exposed so that the UI can be accessed from outside your local network then you should have some form of authentication method enabled in order to access the UI. This is also increasingly required by Trackers and Indexers.

As of ReadAIrr v1, Authentication is Mandatory.

AuthenticationType and AuthenticationMethod are mandatory required attributes in the configuration file.

#Authentication Method

Basic (Browser pop-up) - This option when accessing your ReadAIrr will show a small pop-up allowing you to input a Username and Password. Note this is not recommended and will be removed in the next major version.
Forms (Login Page) - This option will have a familiar looking login screen much like other websites have to allow you to log onto your ReadAIrr. This is recommended.
External - Configurable via Config File Only
- Disables app authentication completely. Use at your own risk especially if exposed to the internet Suggested only if you use an external authentication such as Authelia, Authetik, NGINX Basic auth, etc. you can prevent needing to double authenticate by shutting down the app, setting <AuthenticationMethod>External</AuthenticationMethod> in the config file, and restarting the app. Note that multiple AuthenticationMethod entries in the file are not supported and only the topmost value will be used

#Authentication Required

If you do not expose the app externally and/or do not wish to have auth required for local (e.g. LAN) access then change in Settings => General Security => Authentication Required to Disabled For Local Addresses
- The config file equivalent of this is <AuthenticationType>DisabledForLocalAddresses</AuthenticationType>
<AuthenticationType>Enabled</AuthenticationType> is also a valid value

#How does ReadAIrr find books

{#how-does-readarr-find-books}

This FAQ item is a legacy FAQ Entry. Refer to How does ReadAIrr work? {.is-info}

#How are possible downloads compared

Generally Quality Trumps All. If you wish to have Quality not be the main priority - you can merge your qualities together. See TRaSH's Guide*** {.is-info}

The current logic can be found here.
As of 2022-01-23 the logic is as follows:

Quality
Preferred Word Score
Protocol (as configured in the relevant Delay Profile)
Indexer Priority
Seeds/Peers (If Torrent)
Book Count
Age (If Usenet)
Size

#A Task was Canceled

ReadAIrr received no response from the server the request was made to after 100 seconds.
This is often caused by:
- improperly configured or use of a VPN
- improperly configured or use of a proxy
- local DNS issues
- local IPv6 issues - most common - typically IPv6 is enabled on the host system, but non-functional
- the use of Privoxy and it being improperly configured
- PiHole Rate Limiting requests

#What are Lists and what can they do for me

Lists are a part of ReadAIrr that allow you to follow a given list creator.
Let's say that you follow a given list creator on GoodReads and really like their collection of Great Books and want to add every book on their list. You look in your ReadAIrr and realize that you do not have those books. Well instead of searching one by one and adding those lists and then searching your indexers for those books. You can do this all at once with a List. The Lists can be set to import all the books on that curators list as well as be set to automatically assign a quality profile, automatically add, and automatically monitor that book.

CAUTION: If lists are done improperly they will absolutely wreck your library with a bunch of trash you have no intention of reading. So make sure of what you're importing before you click save. {.is-warning}

It is suggested that you read through the list before you import it into ReadAIrr.

#Why are lists sync times so long and can I change it

Lists never were nor are intended to be add it now they are hey I want this, add it eventually tools.

You can trigger a list refresh manually, script it and trigger it via the API, or add the books directly to ReadAIrr. Lists will otherwise refresh every 24 hours.

This change was due to not have our server get killed by people updating lists every 10 minutes.

#Why can I not add a new book or author to ReadAIrr

ReadAIrr uses GoodReads for book and author information and images like cover and author art, banners and backgrounds. Generally, there are a few reasons why you may not be able to add a book:
GoodReads doesn't like special characters to be used when searching for books through the API (which ReadAIrr uses), so try searching a translated name, and/or without special characters.
You can also add books and authors by GoodReads ID, ISBN ID, or ASIN ID.
The book has an issue with GoodReads API data. Unfortunately this is something we probably cannot solve for you.
The book falls below the settings you've chosen (votes, pages, etc.) to appear in ReadAIrr.

#How do I test the metadata source?

Go to Settings => Development and click Test Metadata Source. ReadAIrr tests the current value in the form before it is saved, so this is the quickest way to validate a hosted source or a custom metadata URL.

The test defaults a blank source to https://api.bookinfo.pro, accepts HTTP/HTTPS URLs, and checks the metadata author/3389 route. Backend code still accepts readarr://metadata/original for compatibility, but the current UI does not present it as a normal option. The result shows success or failure, response detail, and HTTP status when available.

#Metadata Profile "None" allowing Foreign Releases

{#metadata-profile-none-allowing-foreign-releases}

Using a metadata profile of None is useful to only have books explicitly added by the user in ReadAIrr. However, the downside of this is that it opens you up to every edition - including foreign editions - of a book to be available.
To work around this issue create a new Metadata Profile with the popularity threshold described on the settings page

#Book Match is not Close Enough: XX% vs YY% [book]

ReadAIrr compares the to-be-imported file against the matched book and author. Matches below the configured similarity threshold are rejected during automatic import and manual import.
Configure the threshold at Settings => Development => Matching => Minimum Book Match Similarity.
The default is 80, which matches the inherited Readarr behavior. The accepted range is 50 to 100.
Raise the value for stricter matching. Lower it if correct files are being rejected with "Book match is not close enough."

#How can I rename my author folders

{#rename-folders}

The same process applies for moving/changing Author paths as well{.is-info}

Authors
Click on "Author Editor"
Select what authors need their folder renamed
Change Root Folder to the same Root Folder that the authors currently exist in
Select "Yes, move the files"

#How can I mass delete authors from the wanted list

Use Author Editor from the Author tab => Select authors you want to delete => Delete

#How do I update ReadAIrr

{#how-do-i-update-readarr}

{#how-do-I-update-my-readarr}

The first-party container workflow publishes images to GitHub Container Registry from the ReadAIrr/App repo.

Source	Image tag
`dev` branch	`ghcr.io/readairr/app:dev`
`val` branch	`ghcr.io/readairr/app:val`
`prod` branch	`ghcr.io/readairr/app:prod`, `ghcr.io/readairr/app:latest`, `ghcr.io/readairr/app:1`, and `ghcr.io/readairr/app:1.0`
`v*` git tag	matching version tag

For Docker installs, pull the newer image and recreate the container. Do not update the app from inside the running container.

The inherited native updater still uses the branch configured under Settings => General => Updates; the app default is develop. The public update API is served from https://readairr.com/v1/update/{branch} by the ReadAIrr/Site Cloudflare Pages function. If no matching release package exists in the site manifest, the endpoint reports that no update is available.

#Can I update ReadAIrr inside my Docker container

Technically, yes. But you absolutely should not. It is a primary philosophy of Docker. Database issues can arise if you upgrade your installation inside the running container, then later replace the container image with a different build.

#Installing a newer version

#Native

Go to System and then the Updates tab
Newer versions that are not yet installed will have an update button next to them, clicking that button will install the update.

#Docker

Repull your tag and update your container

#Can I switch branches or image tags

For Docker installs, switch by changing READARR_IMAGE and recreating the container.
Moving to a newer image can apply database migrations. Do not assume you can safely go back to an older image afterward.
For native installs, the inherited branch setting still exists under Settings => General => Updates, but only use branches that have packages published by the ReadAIrr update service.
Before changing branches or image tags, make an app backup and keep a copy of the /config directory.

#I am getting an error: Database disk image is malformed

Errors of Error creating log database indicate issues with log.db
- This can quickly be resolved by renaming or removing the database. The logs database contains unimportant information regarding commands history and update install history, and Info, Warn, and Error entries
Errors of Error creating main database or generic database disk image is malformed with no specified database indicate issues with readarr.db
- Continue with the steps noted below
This means your SQLite database that stores most of the information for ReadAIrr is corrupt. Your options are to try (a) backup(s), try recovering the existing database, try recovering the backup(s), or if all else fails starting over with a fresh new database.
This error may show if the database file is not writable by the user/group *Arr is running as. Permissions being the cause will likely only be an issue for new installs, migrated installs to a new server, if you recently modified your appdata directory permissions, or if you changed the user and group *Arr run as.
Your best and first option is to try restoring from a backup
You can also try recovering your database. This is typically the only option for when this issue occurs after an update. Try the sqlite3 .recover command
- If your sqlite does not have .recover or you wish a more GUI (i.e. Windows) friendly way then follow our instructions on this wiki.
Another possible cause of you getting an error with your Database is that you're placing your database on a network drive (nfs or smb or something else not local). SQLite is designed for situations where the data and application coexist on the same machine. Thus your *Arr AppData Folder (/config mount for docker) MUST be on local storage. SQLite and network drives not play nice together and will cause a malformed database eventually.
If you are using mergerFS you need to remove direct_io as SQLite uses mmap which isn’t supported by direct_io as explained in the mergerFS docs here

#How do I Backup/Restore my ReadAIrr

#Backing up ReadAIrr

#Using built-in backup

Go to System => Backup in the ReadAIrr UI
Click the Backup button
Download the zip after the backup is created for safekeeping

#Using file system directly

Find the location of the AppData directory for ReadAIrr
- Via the ReadAIrr UI go to System => About
- ReadAIrr Appdata Directory
Stop ReadAIrr - This will prevent the database from being corrupted
Copy the contents to a safe location

#Restoring from Backup

Restoring to an OS that uses different paths will not work (Windows to Linux, Linux to Windows, Windows to OS X or OS X to Windows), moving between OS X and Linux may work, since both use paths containing / instead of \ that Windows uses, but is not supported. You'll need to manually edit all paths in the database. {.is-warning}

#Using zip backup

Re-install ReadAIrr (if applicable / not already installed)
Run ReadAIrr
Navigate to System => Backup
Select Restore Backup
Select Choose File
Select your backup zip file
Select Restore

#Using file system backup

Re-install ReadAIrr (if applicable / not already installed)
Find the location of the AppData directory for ReadAIrr
- Running ReadAIrr once and via the UI go to System => About
- ReadAIrr Appdata Directory
Stop ReadAIrr
Delete the contents of the AppData directory (Including the .db-wal/.db-journal files if they exist)
Restore from your backup
Start ReadAIrr
As long as the paths are the same, everything will pick up where it left off

#File System Restore on Synology NAS

CAUTION: Restoring on a Synology requires knowledge of Linux and Root SSH access to the Synology Device. {.is-warning}

Re-install ReadAIrr (if applicable / not already installed)
Find the location of the AppData directory for ReadAIrr
- Running ReadAIrr once and via the UI go to System => About
- ReadAIrr Appdata Directory
Stop ReadAIrr
Connect to the Synology NAS through SSH and log in as root

On some installations, the user is different than the below commands: chown -R sc-ReadAIrr:ReadAIrr * {.is-info}

Execute the following commands:

rm -r /usr/local/ReadAIrr/var/.config/ReadAIrr/ReadAIrr.db
cp -f /tmp/Readarr_backup/* /usr/local/ReadAIrr/var/.config/ReadAIrr/

Update permissions on the files:

cd /usr/local/ReadAIrr/var/.config/ReadAIrr/
chown -R ReadAIrr:users *
chmod -R 0644 *

Start ReadAIrr

#Help, Book Added, But Not Searched

ReadAIrr does not actively search for missing books automatically. Instead, a periodic query of new posts is made to all indexers configured for RSS. When a wanted or cutoff unmet book shows up in that list, it gets downloaded. This means that until a book is posted (or reposted), it won’t get downloaded.
If you’re adding an author with books that you want now, the best option is to check the “Start search for missing books” box, to the left of the Add Author button. You can also go to the page for an author you’ve added and click the magnifying glass Search button next to the book you want, or use the Wanted view to search for Missing or Cutoff Unmet books.

#Root path for authors imported from lists becomes “C:” or other weird paths

Sometimes you can get a problem that authors that are imported from your lists, gets imported with the root path set to “C:” or other weird paths.
This is a known issue for when the root path is either not setup during the creation of the list, or if the root path has been deleted after the list was created. Note that this problem can still occur even if the list is edited and the correct root path is set.
Use the Mass Editor to fix paths of existing authors.

#Book Imported, But Source File And Torrent Not Deleted

Check if you have Completed Download Handling - Remove turned on.
If you are using deluge make sure auto-managed is turned on. And that torrents get paused when they reach specified seeding quota.

#Can I disable the refresh books task

No, nor should you through any SQL hackery. The refresh books task queries the configured metadata source and checks to see if the metadata for each book has changed compared to what is currently in ReadAIrr. If necessary, it will then update the applicable books.
A common complaint is the Refresh task causes heavy I/O usage. One setting that can cause issues is "Rescan Author Folder after Refresh". If your disk I/O usage spikes during a Refresh then you may want to change the Rescan setting to Manual. Do not change this to Never unless all changes to your library (new books, upgrades, deletions etc) are done through ReadAIrr. If you delete book files manually or a third party program, do not set this to Never.

#Can I have BOTH an ebook and an audiobook version of the same book

No. With a single ReadAIrr instance, you can have either one or the other, but not both. If you want both, you would need to run two separate instances of ReadAIrr (much like some people run 2 instances of Sonarr or Radarr for 1080p and 4K versions of their media).

#Do I need to use Calibre

No. In general Calibre offers some further enhancement, such as the ability to auto-convert ebooks to another format specific to your e-reader's capabilities, and also to connect to that e-reader. But if you weren't running Calibre prior to installing ReadAIrr, then it's probably going to be of limited added benefit to you to install it, and it's a very large program.

#Why can ReadAIrr not see my files on a remote server

{#why-can-readarr-not-see-my-files-on-a-remote-server}

{#why-cant-i-see-my-files-on-a-remote-server}

For all OSes ensure the user/group you're running *Arr as has read and write access to the mounted drive.
For Linux ensure:
- If you're using an NFS mount ensure nolock is enabled for your mount.
- If you're using an SMB mount ensure nobrl is enabled for your mount.
For Windows: In short: the user *Arr is running as (if service) or under (if tray app) cannot access the file path on the remote server. This can be for various reasons, but the most common is *Arr is running as a service, which causes the issues described below.

#ReadAIrr runs under the LocalService account by default which doesn't have access to protected remote file shares

Run ReadAIrr service as another user that has access to that share
Open the Administrative Tools > Services window on your Windows server.
Stop the ReadAIrr service.
Open the Properties > Log On dialog.
Change the service user account to the target user account.
Run ReadAIrr.exe using the Startup Folder

#You're using a mapped network drive (not a UNC path)

Change your paths to UNC paths (\\server\share)
Run ReadAIrr.exe via the Startup Folder

#Help I have locked myself out

{#help-i-have-forgotten-my-password}

To disable authentication (to reset your forgotten username or password) you will need need to edit config.xml which will be inside the ReadAIrr Appdata Directory

Stop ReadAIrr
Open config.xml in a text editor
Find the authentication method line - will be <AuthenticationMethod>Basic</AuthenticationMethod> or <AuthenticationMethod>Forms</AuthenticationMethod> (Be sure you do not have two AuthenticationMethod entries in your file!)
Remove the entire AuthenticationMethod line
Start ReadAIrr
ReadAIrr will now be accessible without a password. When you open the Web UI, you should be prompted to set a new password and authentication method

#How do I stop the browser from launching on startup

Depending on your OS, there are multiple possible ways.

In Settings => General on some OS'es, there is a checkbox to launch the browser on startup.
When invoking ReadAIrr, you can add -nobrowser (*nix) or /nobrowser (Windows) to the arguments.
Stop ReadAIrr and edit the config.xml file, and change <LaunchBrowser>True</LaunchBrowser> to <LaunchBrowser>False</LaunchBrowser>.

#Weird UI Issues

If you experience any weird UI issues like the Library page not listing anything or a certain view or sort not working, try viewing in a Chrome Incognito Window or Firefox Private Window. If it works fine there, clear your browser cache and cookies for your specific ip/domain. For more information, see the Clear Cache Cookies and Local Storage wiki article.

#Invalid Certificate and other HTTPS or SSL issues

{#invalid-certificate-and-other-HTTPS-or-SSL-issues}

For local download clients, do not enable SSL in ReadAIrr unless the client is actually serving HTTPS with a certificate trusted by the ReadAIrr host/container.
If ReadAIrr is behind a reverse proxy, terminate HTTPS at the proxy and make sure WebSocket/SignalR forwarding is configured.
If a private certificate authority is involved, install or mount the CA certificate where the ReadAIrr runtime trusts it rather than disabling validation globally.

#VPNs, Jackett, and the *ARRs

For comprehensive VPN guidance, see the dedicated VPN Guide page. {.is-info}

Unless you're in a repressive country like China or Australia, your BitTorrent client is typically the only thing that needs to be behind a VPN. Usenet does not require VPN protection as it uses encrypted SSL connections. For most countries including the UK, using secure DNS (like Cloudflare's 1.1.1.1 or Google's 8.8.8.8) is sufficient to resolve access issues without requiring a VPN. Other *Arr apps not connecting to trackers should not be behind a VPN. Because the VPN endpoint is shared by many users, you can and will experience rate limiting, DDOS protection, and ip bans from various services each software uses.

To be clear it is not a matter if VPNs will cause issues with the *Arrs, but when: image providers will block you and cloudflare is in front of most of *Arr servers (updates, metadata, etc.) and liable to block you too {.is-warning}

Many private trackers will ban you for using or accessing them (i.e. using Jackett or Prowlarr) via a VPN.

#Jackett's /all Endpoint

{#jackett-all-endpoint}

The Jackett /all endpoint is convenient, but that is its only benefit. Everything else is potential problems, so adding each tracker individually is required. Alternatively, you may wish to check out the Jackett & NZBHydra2 alternative Prowlarr
January 20 2022 Update: Jackett /all endpoint is no longer supported (e.g. warnings will occur) as of 0.1.0.1188 due to the fact it only causes issues.
The Jackett /all endpoint is convenient, but that is its only benefit. Everything else is potential problems, so adding each tracker individually is now required.
Even Jackett's Devs says it should be avoided and should not be used.
Using the /all endpoint has no advantages, only disadvantages:
- you lose control over indexer specific settings (categories, search modes, etc.)
- mixing search modes (IMDB, query, etc.) might cause low-quality results
- indexer specific categories (>= 100000) cannot be used.
- slow indexers will slow down the overall result
- total results are limited to 1000
- if one of the trackers in /all returns an error, *Arr will disable it and now you do not get any results.

#Jackett /All Solutions

Add each tracker in Jackett manually as an indexer in *Arr
Check out Prowlarr which can sync indexers to *Arr and from the Lidarr/Radarr/ReadAIrr development team.
Check out NZBHydra2 which can sync indexers to *Arr. But do not use their single aggregate endpoint and use multi if sync will be used.

#Why are there two files? | Why is there a file left in downloads

This is expected. With a setup that supports hardlinks, double space will not be used. Below is how the Torrent Process works.

ReadAIrr will send a download request to your client, and associate it with a label or category name that you have configured in the download client settings. Examples: movies, tv, series, music, etc.
ReadAIrr will monitor your download clients active downloads that use that category name. This monitoring occurs via your download client's API.
Completed files are left in their original location to allow you to seed the file (ratio or time can be adjusted in the download client or from within under the specific download client). When files are imported to your media folder will hardlinkthe file if supported by your setup or copy if not hard links are not supported.
If the "Completed Download Handling - Remove Completed" option is enabled in ReadAIrr's settings, ReadAIrr will delete the original file and torrent from your download client, but only if the download client reports that seeding is complete and torrent is stopped.

Hard links are enabled by default. A hard link will allow not use any additional disk space. The file system and mounts must be the same for your completed download directory and your media library. If the hard link creation fails or your setup does not support hard links then will fall back and copy the file. {.is-info}

#Calibre is saying "Calibre rejected duplicate book" but it's not

If you're using Calibre integration, Calibre is occasionally going to reject a book, saying it's a duplicate. It's probably not actually a duplicate. If this happens, there's not much ReadAIrr can do, and you will need to unmonitor that book to prevent ReadAIrr from continuing to try to grab it and push it to Calibre. This is just one of the fun downsides to Calibre integration.