Shields Debugging Guide

Brave Shields is Brave's primary layer of privacy protection against websites. Brave Shields controls several privacy features to provide this protection.

As websites change, Shields can break by failing to block desired resources and unintentionally blocking site functionality. To diagnose and resolve these issues, follow these steps.

Isolate the source of the issue

Very important: Rule out non-Shields causes first. Often, web compatibility issues are not actually caused by Shields.

1. Try another browser: Chrome, Firefox, Safari (in that order). If the bug reproduces there too, it's a site bug, not a Brave bug.
2. Disable all other adblockers and privacy tools, including any network-level blocking via Pi-hole or AdGuard DNS.
3. Reproduce in a fresh private window (no extensions, clean storage). If the issue disappears, it is probably related to extensions or browser storage, not Shields.

Shields is breaking a site

Issue Diagnosis

"Adblocker detected" or "unsupported browser" errors

Websites often throw errors for adblocker detection if their first-party ads are being blocked.

1. Switch ad blocking mode from Aggressive to Standard and check if the issue persists
2. If it persists, switch the ad blocking mode from Standard to Disabled
3. Allow third-party cookies
4. Disable Shields for the site from within the Shields panel

If the error is cleared, anti-adblock detection is confirmed for this page.

Missing or broken functionality (embeds, logins, video players)

Sometimes, when blocking certain functionality for privacy purposes, there are legitimate features of a website that get affected.

1. In the Shields settings, test to see if unblocking cookies and disabling ad/tracker blocking fixes the issue
2. If the issue persists, go to the Shields filter settings and try disabling the enabled filter lists to see if any of these fix your issue
3. Disable Shields for the site from within the Shields panel

Layout issues, excessive whitespace, hidden elements

Usually caused by cosmetic filter rules hiding an element, leaving an empty container behind.

1. Inspect the HTML of the page (right click the empty region) and look for any elements with display: none; styling
2. Toggle Block trackers & ads to Disabled
3. If the issue persists, go to the Shields filter settings and try disabling the enabled filter lists to see if any of these fix your issue
4. Disable Shields for the site from within the Shields panel

Issue Remediation

These issues often involve adjustments to filter lists to restore the site's functionality. Please create a bug report for Brave with the steps taken to resolve the issue.

Shields is failing to block desired resources

Issue diagnosis

Ads are visible on the page

1. Ensure Shields are active for the current page
2. Confirm the Trackers & ads blocking mode is set to Standard. This will block third-party ads
3. If the issue persists, select Aggressive. This will block first-party ads
4. If the ad still appears, this is a Shields issue

Cookie notice is visible on a page

1. Ensure Shields are active for the current page
2. Check the Shields filter settings to ensure Cookie notice blocker is enabled
3. If this is enabled, and the cookie notice continues to appear, this is a Shields issue

Suspected cookies or trackers

1. Ensure Shields are up for the current page and check the Shields settings to ensure the following settings are set
   • Adblock-Only mode = disabled
   • Block cookies = Block third-party cookies
   • Trackers & ads blocking = Standard
2. Check the devtools to ensure this is working correctly
   • The network tab will show any trackers that may be loaded on the page while indicating the ones that have been blocked
   • The cookies section in the application tab will have different subheadings for each domain
3. If you notice other domains that cookies are being saved to, or network requests that appear to be tracking related, there may be an issue with Shields

Issue Remediation

If the issue persists, it is likely related to the filter lists.

1. Go to the Shields filter settings and enable lists that are relevant to your issue
2. Apply a custom filter rule in the Shields filter settings
3. Report the issue to Brave using the Report broken site button within the Shields panel

Debugging tools reference

• Shields panel (Shields Icon in the address bar) - allows enabling/disabling Shields on per-site basis
• brave://settings/shields - global Shields settings.
• brave://settings/shields/filters - list of active filter lists and custom filter tool
• brave://version - version info. Helpful when reporting bugs

Reporting the issue

If you've narrowed down the issue to a Shields issue, report the site by clicking the Report broken site button within the Shields panel. This files a report with necessary info for Brave's webcompat team.

If you've narrowed down the issue to a Brave browser bug, follow the steps to file a bug report with Brave brave/brave-browser issues.