BrowserFairyBrowserFairy

Reference

Troubleshooting

Fix links opening in the wrong browser, default-browser problems, extensions, and profiles.

When links don't go where you expect, the cause is almost always one of a handful of things. Work through the symptom that matches what you are seeing, and follow the steps in order.

If clicking a link in Mail, Slack, or another app opens it in some browser without BrowserFairy stepping in, two things need to be true: BrowserFairy must be your default browser, and it must be running.

  1. Click the BrowserFairy icon in the macOS menu bar (the status area at the top right of your screen), then choose Settings….
  2. In the General pane, look at the Default Browser section.
  3. If you see BrowserFairy is your default browser, BrowserFairy is set up correctly. If you see anything else, read on.

If the status reads BrowserFairy only handles some web links, you are in the partial state: another browser still owns one of the two link types BrowserFairy needs. BrowserFairy must own both http and https to intercept links reliably.

  1. Click Make Default.
  2. macOS shows its own confirmation dialog asking if you want to change your default web browser. Confirm it.
  3. Wait a moment. The status can take up to about 2 seconds to update, then it should read BrowserFairy is your default browser.

If the status reads BrowserFairy is not the default browser, do the same: click Make Default and confirm the macOS dialog.

Settings, General pane. The Default Browser section shows whether BrowserFairy owns your links, with the Make Default button.

Because BrowserFairy is a menu bar app, it has no Dock icon and no window of its own when idle. If the menu bar icon is gone entirely, BrowserFairy is not running. Open it from your Applications folder, and the menu bar icon comes back. For a deeper walkthrough, see Make BrowserFairy your default browser.

Want it to start automatically?

BrowserFairy has no built-in launch-at-login setting. To start it on every login, add BrowserFairy in System Settings > General > Login Items.

If BrowserFairy is routing links but sending them to the wrong place, the issue is usually rule order or a rule that is turned off.

BrowserFairy checks rules from top to bottom and uses the first one that is turned on and whose conditions match. This is first-match-wins, so a broad rule placed above a specific one will grab links before the specific rule ever runs.

  1. Open the BrowserFairy menu bar icon and choose Rules Editor….
  2. Read your rules from top to bottom. Put specific rules above broad ones.
  3. Reorder by dragging a rule up or down in the list.

Also confirm the rule you expect is actually active:

  • A rule that is turned off is skipped entirely. Turn it on.
  • On the free plan, only the first 3 rules in the list stay active. A rule lower in the list shows the banner This rule is inactive and won't route any links. It is still saved, but it routes nothing until you move it into the top 3 or subscribe. See Free and Pro.

For the full mental model, including what happens when nothing matches, read How routing works.

The Rules Editor. Rules run top to bottom, so order is priority. Drag to reorder.

Default-browser routing only covers links you click in other apps, like Mail or Slack. A link you click while you are already inside a browser stays in that browser unless you install the BrowserFairy extension for it.

  • In Safari, turn on the built-in extension under Safari Settings > Extensions. It is named BrowserFairy Safari Extension and ships inside the app, so there is nothing to download.
  • In Chrome, Edge, Firefox, or Opera, install the BrowserFairy extension from that browser's own extension store.

Each extension adds a toolbar button labeled BrowserFairy that sends the page you are viewing, and a right-click menu item on links labeled Open with BrowserFairy. See Browser extensions for the install steps.

Extensions do nothing

If you click the BrowserFairy toolbar button or Open with BrowserFairy and nothing happens, the usual cause is that the BrowserFairy app is not there to receive the link. The extension hands the link to the app through its link handler, so the app must be installed and running.

  1. Confirm BrowserFairy is running: look for its icon in the macOS menu bar. If it is missing, open BrowserFairy from your Applications folder.
  2. For Safari specifically, confirm the extension is enabled in Safari Settings > Extensions (look for BrowserFairy Safari Extension with its checkbox turned on).

When everything is in place, sending a link from the extension opens the Browser Launcher so you can pick a browser by hand.

What you see after the extension sends a link: the Browser Launcher opens for that link so you can choose a browser.

No extra setup needed

You do not need to configure native messaging or run any installer for the extensions. If the toolbar button does nothing, the fix is to make sure BrowserFairy itself is installed and running, not to reinstall anything.

A condition that uses Link clicked matches the app the link came from. Some apps hand their links to a helper app first before macOS passes them along, so the source app BrowserFairy sees is not always the one you expected. When that happens, a Link clicked rule fires inconsistently.

The fix is to make the rule less dependent on the source app. Add a Link address condition alongside the Link clicked one, then combine them so the rule still matches on the link text itself. See Conditions for how to combine conditions with Any, All, and None.

Open link withHeliumin profileNimbus | alex.riverawhen
Anyof the following are true
Link clickedinSlack
A Link clicked rule. If the source app is unreliable, pair it with a Link address condition so the rule still matches.

BrowserFairy expands only very short links before matching: roughly 30 characters or fewer, with a tiny host and path and no ? query or # fragment. For one of those, it follows the redirect (a quick lookup with a 2 second timeout) and matches the final address. Normal links are matched exactly as they are, without expansion.

Two things can make a short link miss your rules:

  • The link is longer or more complex than the expansion rule allows, so BrowserFairy matches the short address as-is.
  • The redirect service is slow and does not answer within the 2 second window, so BrowserFairy matches the original short address.

To route these reliably, write a condition that matches either the final address you expect, or the short-link domain itself. For example, a Link address condition that uses "contains" on the shortener's host will match the short link directly. See Conditions for the operators available.

Browser profiles aren't working

Profile routing (opening a link in a specific profile like Work or Personal) needs BrowserFairy Pro plus a one-time setup. Profiles are supported in Chrome, Firefox, Brave, Edge, Helium, and Opera. Safari does not support profiles.

If a rule that targets a profile is opening the browser but ignoring the profile, check these in order:

  • Your subscription. If your Pro subscription has lapsed, the rule still opens the browser, just without the saved profile.
  • The setup. In Settings > General > Browser Profiles, Enable browser profiles must be on and setup must be complete. When it is, you see Setup complete. Browser profiles are now enabled.
  • The profile itself. If the saved profile was renamed, removed, or its access was turned off, the rule opens the browser without that profile.

If setup looks incomplete or the access was lost, re-run Set Up in Settings > General. The full walkthrough is in Browser profiles.

The Browser Profiles controls live in Settings, General. Enable browser profiles and complete setup before assigning profiles to rules.

A rule's browser is missing

If the browser a rule targets is not installed on your Mac, BrowserFairy does not stop. It skips that rule and moves on to the next one that matches, and if nothing else matches it uses your Fallback browser. So an uninstalled browser quietly defers to your other rules rather than breaking routing. If a rule seems to be ignored, confirm its target browser is actually installed, or point the rule at a browser you have.

Recovering your rules

If rules went missing or an edit went wrong, you have two ways back.

  • BrowserFairy writes automatic safety backups before risky changes (deleting rules, importing, the first rule change each time you use the app, and app updates) and keeps the 10 most recent.
  • If you exported a .bf file earlier, you can bring it back. Importing merges into your current rules rather than wiping them: a rule you already have is updated only if the imported copy is newer, and rules you don't have are added. After importing, check the order, since order is priority. See Import and export. (Import and export are Pro features, alongside unlimited rules, browser profiles, and priority support.)

Still stuck

If none of the above fixed it, contact support and we will help. Pro subscribers get priority support.

Open the BrowserFairy menu bar icon, choose the Help submenu, then Contact Support, or visit the contact page. To help us reproduce the problem quickly, include:

  • The link you clicked.
  • The browser you expected it to open in.
  • The browser that actually opened.
  • The rule you thought should have matched.