Troubleshooting

A filter stopped working

Something you hid is showing up again — Shorts are back in the feed, or the members badge stopped being filtered.

CleanWatch works by matching YouTube's own page markup. That markup has private, generated class names, and when YouTube renames one the rule built on it stops matching and does nothing. There is no error. This is the single most common way this extension breaks, and it is why v1.21.0 added a check for it.

If the popup shows an amber "Some filters may need an update" notice, that check has already caught it. Open the Dashboard, find the Filter health card, press Copy report, and paste it into an issue. The report is a few lines of selector names and miss counts — no history, no URLs, nothing about what you watched.

If there is no notice, the check may not have run yet. It runs a few seconds after a page settles, at most once every ten minutes, and only calls a rule broken after it has missed on three separate page views. So it takes roughly half an hour of normal browsing to reach a verdict. That delay is deliberate: a page that has not finished rendering looks exactly like a broken selector, and warning on a single reading would cry wolf constantly.

To check immediately, open the console on a YouTube page and run:

__CW_AUDIT_SELECTORS__()

You get a table of every selector and whether it currently matches anything. Rows marked DEAD found nothing where they should have. skipped means the selector does not apply to this page type, and empty means it is optional and legitimately absent. One DEAD on a page still loading means nothing — reload, let the feed fill in, and run it again.

Clearing the record (Dashboard → Filter health → Clear) resets the observations, not the verdict. If a rule is genuinely broken it will read dead again and the card comes back.

Videos take a long time to start

If playback sits on a spinner for several seconds before the first frame, and your connection is otherwise fine, the cause is often a single unreachable CDN node rather than YouTube or your bandwidth.

YouTube hands the player a primary and a backup video host. When something on the network path breaks the connection to the primary — a middlebox, a broken ISP-hosted cache appliance — a strange thing happens: the first request on a fresh connection answers in tens of milliseconds, and every reuse of that same connection hangs forever. The player has no fast-fail logic, so it waits out its own timeout of about 5.4 seconds before trying the backup, and pays that again on every chunk of video.

One captured session spent 16.2 seconds stalled against 1.8 seconds of actual transfer, and took about 10 seconds to reach the first frame — while the backup host, when finally tried, delivered 12 MB in 830 ms.

Fail over stalled video servers (Watching → Video Player, on by default) handles this. It aborts a video request that has produced no response headers within the stall timeout, so the player fails over immediately instead of waiting. A host that stalls twice is skipped without even opening a connection for the next minute, then given one more chance.

If videos still start slowly, try raising Stall timeout (ms) from its default of 2000. A working server answers in well under a tenth of a second, so 2000 ms is far outside normal — but on a very slow or high-latency link, headers can legitimately take longer.

If playback got worse after v1.21.0, turn the toggle off and tell us. That would mean the guard is aborting requests that would have succeeded, which the threshold is supposed to make impossible.

The learned per-host verdicts are held in memory only and never saved, so moving between networks — or your ISP repairing the path — clears them automatically.

Sync problems

"Group not found" — the sync code is wrong, or the group was purged. Groups are deleted after 365 days with no activity; any sync resets that timer, and the extension warns you as the deadline approaches.

"Device limit reached" — a group holds at most 10 devices. Remove one from the device list before adding another.

Rate limited — 120 requests per minute per IP, 180 per minute per group. Normal use does not come close; this usually means several devices retrying at once. Wait a minute.

Settings are not arriving — sync is not live replication. It reconciles on a schedule and on demand. Force it from Settings → Data & Sync → Server sync.

Nothing works and you self-host — check the API base URL in Settings, and that /api/healthz on your instance answers {"ok":true}.

Bear in mind the server cannot help you recover anything: it stores ciphertext it has no key for. Lose your sync code and the data there is unreadable, by us and by you. Export your settings to a file as a real backup.

The settings page is blank

Fixed in 1.18.1, which affected 1.17.0 and 1.18.0. Update.

If it happens on a current version, it is a script error rather than a styling problem — open the console on the settings page and file what it says. There is a test suite that loads every extension page exactly as the browser does specifically to stop this reaching a release, so an occurrence is worth reporting.

Reporting something else

Open an issue with:

CleanWatch version (bottom of Settings, or chrome://extensions)
Browser and version
The page it happens on — home, watch, search, subscriptions
Whether it still happens with other extensions disabled (uBlock Origin and Return YouTube Dislike also modify these pages)
Console output, if any

A settings export helps for anything configuration-shaped. It contains your settings and blocklists — no watch history — so glance through it before attaching.