2.9 KiB
name, description
| name | description |
|---|---|
| arr-cli/troubleshooting | Common pitfalls, FAQs, and guidance on when not to use the arr-cli skill. |
Troubleshooting & FAQs
Common Pitfalls
Looking up adds an unmonitored record
radarr-cli lookup --tmdb-id N silently creates an unmonitored record. This is a Radarr API design — there's no pure "lookup without adding." For existence checks, filter the movie list instead:
# ✅ Correct — no side effects
radarr-cli --json movies | jq '.[] | select(.tmdbId == 12345)'
# ❌ Wrong — creates phantom unmonitored record
radarr-cli lookup --tmdb-id 12345
Adding requires a root folder path
radarr-cli add --root /movies — the root folder must be an exact path known to Radarr. Discover available paths:
radarr-cli root-folder
Commands appear to hang on large libraries
The movie and series endpoints return the full collection — no server-side pagination. On libraries with 2500+ movies, this can take a few seconds. Use --limit N for faster results:
radarr-cli movies --limit 10
JSON output mixed with warning lines
Occasionally Python deprecation warnings can bleed into --json output. If json.loads() fails, filter lines that start with [ or { before parsing.
Sonarr wanted endpoint is paginated
The wanted endpoint returns a totalRecords field. Use --limit to control page size. Results are capped at the server's max page size.
When Not to Use
- Media playback — this CLI manages the library, not plays content. Use Jellyfin.
- *First-time arr setup — assumes Radarr/Sonarr are already installed and configured. See
radarr.videoorsonarr.tv. - Bulk library migration — for large-scale imports, use Radarr/Sonarr's built-in tools.
- Streaming service status — this won't tell you if a streaming service is down.
FAQ
Q: Why use --tmdb-id instead of a title search? A: Titles can differ between TMDb and Radarr (special characters, subtitle formatting, year disambiguation). The TMDb ID is the canonical key shared by both systems.
Q: Can I add a movie that's not released yet?
A: Yes. Use --availability announced for unreleased films, --availability inCinemas for current theatrical releases. Don't use --search for unreleased content — there's nothing to search for.
Q: How do I find a movie's TMDb ID?
A: Use radarr-cli lookup --term "title" --json — the results include tmdbId. Or search themoviedb.org directly — the ID is in the URL.
Q: How do I find a series' TVDb ID?
A: Use sonarr-cli lookup --term "title" --json — results include tvdbId. Or search thetvdb.com.
Q: What does quality profile 4 vs 5 mean?
A: Profile IDs vary by setup. Use radarr-cli quality-profile to list all profiles with their names:
- 4 is typically HD-1080p
- 5 is typically Ultra-HD (4K)
- Run the command to see your actual configuration