Skip to content

Clarify Plex watchlist rule behavior and cloud lookup limitations #93

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enoch85 merged 2 commits into from
Jun 7, 2026
Merged

Clarify Plex watchlist rule behavior and cloud lookup limitations #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cc5cbd
Initial plan
Copilot Jun 7, 2026
69e1ec4
docs: clarify Plex watchlist rule behavior
Copilot Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/Glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,7 +355,7 @@ List of labels associated with the Plex item.
#### Watchlisted by (username)

:::info
List of users that have the Plex item in their watchlist. This does not work with private watchlists. This rule is experimental and might not work for all use cases. Plex only.
List of Plex users that have the item in their watchlist. Maintainerr scans all users returned by the Plex server account list for this lookup, not only the current user, and there is currently no per-user exclude option. Private watchlists can produce expected warnings because they are not visible to Maintainerr. This rule depends on Plex cloud services such as `plex.tv` and `community.plex.tv`, is experimental, and might be more fragile than purely local metadata rules. Plex only.

:::

Expand All @@ -366,7 +366,7 @@ List of users that have the Plex item in their watchlist. This does not work wit
#### Is Watchlisted

:::info
Indicates whether the item is on any user's Plex watchlist. Plex only.
Indicates whether the item is on any Plex user's watchlist. Maintainerr checks all users returned by the Plex server account list for this lookup, not only the current user, and there is currently no per-user exclude option. Private watchlists can produce expected warnings because they are not visible to Maintainerr. This rule depends on Plex cloud services such as `plex.tv` and `community.plex.tv`, not only the local Plex server. Plex only.

:::

Expand Down
20 changes: 20 additions & 0 deletions docs/Rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,26 @@ The watch-history getters keep these cases separate: a confirmed empty history r

:::

:::warning Plex Watchlist Rules
`Watchlisted by` (`Plex.watchlist_isListedByUsers`) and `Is Watchlisted` (`Plex.watchlist_isWatchlisted`) do not only check the current Plex user. Maintainerr scans every user still returned by the Plex server account list and then tries to resolve the related Plex.tv / community usernames and UUIDs needed for watchlist lookups.

Current limitations and behavior to expect:

- There is currently no per-user exclude option for Plex watchlist scanning.
- If a removed Plex friend is still returned by the Plex server account list, Maintainerr can still try to scan that user.
- Private watchlists can produce expected warnings because those watchlists are not visible to Maintainerr.
- These rules depend on Plex cloud services such as `plex.tv` and `community.plex.tv`, not only your local Plex server.
- `Watchlisted by` remains experimental and is generally more fragile than purely local metadata rules.

Troubleshooting tips:

- Verify the affected user is still returned by the Plex server account list.
- Verify the watchlist is public if you expect Maintainerr to see it.
- Do not expect reauthing Plex or changing the local Plex IP to fix this specific lookup path by itself.
- `Test Media` can still work while a full rule run fails with repeated Plex cloud timeouts such as `ECONNABORTED`. That usually points to repeated cloud lookups during the full run, not necessarily a local Plex configuration problem.

:::

## Creating rules

### General
Expand Down