Troubleshooting

Links still open in my old browser

LinkUnbound isn’t the default browser yet, or something took the role back.

1. Open Settings › Links. If it says Windows (macOS) is not sending links here yet, follow First steps.
2. If it says LinkUnbound is not receiving links, the reason and the button that fixes it are right there (usually Repair). See Settings.
3. Some browsers ask to become the default again after an update. If you said yes, choose LinkUnbound again.

Teams or Outlook open Edge

Both have a setting of their own that decides where their links go, and that’s the first thing to change:

• Teams: Settings › Files and links › Link open preference: choose the default browser.
• Classic Outlook: File › Options › Advanced › Open hyperlinks from Outlook in: choose Default Browser.

Microsoft moves these menus around; if they’re not there, look for «link open preference» or «hyperlinks».

What’s left after that is a channel some Microsoft apps (and Windows widgets and search) use to send links straight to Edge, skipping the default browser. Windows 11 no longer lets another application stand in the middle of it, so no browser picker can intercept those. When such a link arrives wrapped in a SafeLink, LinkUnbound unwraps it; the rest is Microsoft’s to change.

The picker doesn’t appear, nothing happens

• LinkUnbound isn’t running. Look for its icon in the tray (behind the ^ arrow on Windows) or the menu bar. If it isn’t there, open LinkUnbound from the Start menu or Applications.
• There’s a rule for that link. It opened straight away in a browser that may be behind other windows. With the notice turned on you’ll see A rule decided for …; check Settings › Rules.
• On a Mac, it’s running from the disk image. Move it to Applications and open it from there.

I don’t see the tray icon (Windows)

It’s in the hidden icons, behind the ^ at the right of the taskbar. Windows keeps every new app there until you drag it onto the bar, or turn it on under Windows Settings › Personalization › Taskbar › Other system tray icons.

Closing the settings window never stops LinkUnbound; only Exit in the tray menu does.

A browser isn’t in the picker

1. Settings › Browsers › Look for browsers again. Useful if you installed it after LinkUnbound.
2. Check it isn’t hidden (it says hidden from the picker).
3. If the system doesn’t register it (portable browsers, development builds), Add a browser by hand. See Browsers and profiles.

If a well-known browser isn’t detected, open an issue with its name and version.

A profile is missing, or wrong

Only Chromium-based browsers’ profiles are detected. If you renamed or created one, Look for browsers again. For Firefox profiles, duplicate Firefox and add -P "Profile name" as its argument.

A rule isn’t doing what I expected

Remember the order (more in Rules):

1. A rule from an app wins over any address rule.
2. Then the most precise: exact URL, then subdomain, then site.

So if docs.google.com opens in Brave when you expected Chrome, check whether you clicked it in an app that has a From rule. The notice (A rule decided for …) names the rule that decided each time; turn it on under Settings › Application if it’s off.

Undo on that notice deletes the rule that decided.

A browser won’t open in private

Either it has no private mode, or LinkUnbound doesn’t know its switch. For a custom browser, set the Private window argument under Settings › Browsers › Edit.

Messages you might see

Message	What it means
The browser would not start	The program failed to launch. Check its path in Settings › Browsers
That browser is no longer configured	A rule points to a browser that was removed. Change the rule
The profile … is no longer there	The Chromium profile was deleted or renamed. Look for browsers again, and fix the rule
Your rules could not be read	rules.json is damaged. Links will ask until it’s fixed; see below
The rule could not be saved	The data folder couldn’t be written. Check the disk isn’t full and the folder is yours
No browser to offer. Add one in Settings.	Every browser is hidden or none was detected

If rules.json is damaged, close LinkUnbound, open the file in a text editor and look for the problem (or restore a backup), or use Settings › Maintenance › Reset the configuration to start fresh. A preferences.json that can’t be read is moved aside as preferences.unread.json and defaults are used.

Windows shows warnings when installing

The installer from GitHub is signed with a self-signed certificate. Choose Keep in the browser and More info › Run anyway in SmartScreen. It only happens once. To avoid it, install from the Microsoft Store. See Installation.

Putting together a report

1. Open Settings › About › If something goes wrong.
2. Save report… writes one Markdown file with LinkUnbound’s version, your system, the registration status, your browsers, preferences, rules and the recent errors. It doesn’t contain the addresses you visit. The message on screen says where it was saved.
3. Read it: it’s plain text. It names the sites you have rules for; remove anything you’d rather not share.
4. Open an issue and attach it.

In the issue, tell us:

• your system and its version;
• the LinkUnbound version (in Settings › About) and where you installed it from (Store, GitHub, Homebrew);
• what you did, what you expected, and what happened instead;
• the app the link came from, and the browser you expected.

For security problems, don’t open a public issue: see SECURITY.md.