Fluid not working: what to check, in order

When an app built with Fluid stops behaving, the temptation is to open preferences and start toggling. That is the slowest possible route, because the settings panes sit above two layers that can produce identical symptoms from completely different causes. Working through the checks in a fixed order costs a few minutes and eliminates most of the guessing. There is also one background fact that shapes everything below: the published build is 2.1.2 and its contents date from 2018, so "update to a newer version" is not on the list of available fixes. The order of the checks has to carry the weight instead.

Check 1: does it launch at all

Start here even when the symptom seems unrelated, because a launch problem masquerades as everything else.

Both the creator and every app it produces contain Intel instructions only. On an Apple Silicon Mac they run through Rosetta translation, and if that translation layer has never been installed, macOS offers to install it rather than opening the app. Accepting the prompt resolves it. Apple states the position directly.

Rosetta enables a Mac with Apple silicon to run Intel-based apps. Support for Rosetta will end in a future version of macOS, so check with the app's developer for an updated version. Source: support.apple.com

Confirming which kind of app is on the disk takes one step. Select it in the Finder and press Command+I. The Kind field reads Application (Intel), Application (Universal) or Application (Apple silicon). An app built with Fluid reads Intel.

The same page notes that Rosetta remains available through macOS 27, and that from macOS 28 it is retained only for certain older games that depend on Intel frameworks. That is a planning horizon rather than a current fault, and it does not explain a failure today.

Check 2: a security warning rather than a launch failure

A warning dialog is a different problem from a bouncing icon, and it is worth separating the two before touching anything.

The distributed archive is signed with a Developer ID certificate and it is notarized, which means a fresh download from the official site opens on a current Mac without being blocked. When a block does appear, the cause is almost never the signature itself.

Three situations account for most of them. The first is a copy carried over from an old machine or restored from a backup, which may have been altered after signing and no longer matches its own signature. The second is a first launch on a network that cannot reach Apple, since the notarization check happens online at that moment. Running it once on an ordinary connection settles it permanently. The third is an archive that was unpacked with a tool that did not preserve the bundle intact.

The useful diagnostic is to delete the copy, download fresh from the official site, and launch that. If the fresh copy opens, the old one was the problem and no setting needed changing.

Check 3: links leaving the window when they should stay

This is the single most reported symptom, and it has one explanation in almost every case.

A created app holds a list of URL patterns describing the territory it is responsible for. Anything outside that territory is handed to the default browser instead of being loaded inside the window. A newly created app starts with exactly one pattern in that list, covering Google. Any site that does not match one of the built-in presets therefore begins life with an effectively empty territory, and the first internal link clicked leaves for Safari or Chrome.

The fix is to add the service's own domain as a wildcard pattern in the Whitelist pane. The panes in a created app are General, Tabs, Security, Shortcuts, Handlers, Whitelist and four browser side panels, so the list is not hard to find once the name is known. Patterns also accept regular expressions when wrapped in slashes, which is shorter for business services that put a per-customer subdomain in front of every URL.

Worth knowing before spending time here: the shipped table of presets covers 43 sites, and it reflects the web as it stood before 2018. Campfire, Highrise, Feedly, Flickr and Google Notebook are all in it. Slack, Notion, Microsoft 365 and Okta are not. Anything launched in the last several years will need its patterns entered by hand, and that is expected behaviour rather than a defect.

The opposite symptom exists too. If external links refuse to leave and open inside the app instead, the switch allowing navigation to any domain is on, or the setting that inverts the meaning of the list has been enabled. Both live in the Security pane and both are reversible in one click.

Check 4: sign in that never completes

A sign in loop looks like an authentication problem and is usually a routing problem, which is why it belongs immediately after check 3 rather than in a category of its own.

Modern sign in flows bounce through a domain that belongs to an identity provider rather than to the service being signed into. The window follows the redirect, lands on a domain outside its territory, and hands the whole flow to the default browser. The browser completes the sign in and sets a cookie, but it sets it in the browser, so the app window comes back to a login screen and the cycle repeats.

The fix is to add the identity provider's domain to the same pattern list, not just the service's. This is the reason the built-in presets for older services list a sign in domain separately from the main site: the entry for one shopping service lists a completely different domain used only for its login step, and the entry for a project tool lists the separate host that used to handle its authentication. The same structure is needed for anything current, entered manually.

A related case is an app that keeps asking for sign in on every launch even though the flow completes. Each app maintains its own cookie store, so a fresh app genuinely does not know about a session established in a browser. Signing in once inside the app window, rather than authorising it from the browser, is what persists.

Check 5: menu items that are greyed out

Some functions are present in the menus but inactive, which reads as a bug and is not one.

Three capabilities are gated behind the five dollar licence: pinning an app to the status bar, userscripts and userstyles, and full screen mode. Creating apps is not gated, and there is no limit on how many can be created. A greyed out Pin to Status Bar or a Userscripts window that refuses to open is the licence state showing through, not a broken installation.

This matters for diagnosis because it sets a boundary. Time spent trying to make a menu item respond is wasted when the item is behaving exactly as designed. Confirm the licence state first, then decide whether the feature is worth five dollars, and move on either way.

Check 6: an update check that never finds anything

Choosing Check for Updates and being told the app is current, repeatedly, is correct behaviour rather than a stuck updater.

The update feed the app polls was last rebuilt on 19 October 2018, and the newest release it advertises is 2.1.2, which is what is already installed. The response is accurate. The mechanism works and there is simply nothing newer on the other end of it.

The practical consequence is that "wait for a fix" is not a strategy here. Any problem that survives the checks above will still be present next month. That is a reason to set a time limit on debugging, which the last check addresses.

Check 7: rendering that looks wrong

Display problems split cleanly into two causes, and one comparison separates them.

Open the same page in Safari on the same Mac. Fluid draws with the WebKit that macOS provides rather than with a bundled engine, so an app and Safari are showing the page through closely related machinery. If Safari renders it correctly and the app does not, the difference is in the app's own settings. If both are wrong, the site or the operating system is responsible and no setting inside the app will help.

When the difference is local, the user agent setting is the first suspect. The presets that ship are Safari 12, iOS Safari 12 for iPhone and iPad, Chrome 70, Firefox 62 and Internet Explorer 11, all from 2018. A site told it is talking to Chrome 70 may serve a degraded layout or refuse outright. The default option builds its string from the running system and stays current, so returning to it resolves a surprising share of the reports where a site claims the browser is unsupported.

Two smaller settings occasionally matter. Plug-ins and Java both ship disabled, which is the right default but will break a very old internal tool that depends on them. Downloads land in the standard Downloads folder unless the path was changed, so a file that seems to have vanished is usually sitting there.

One case that often gets misdiagnosed is an internal admin panel served over plain http rather than https. The app template ships with arbitrary loads permitted, so an insecure internal address loads without the app objecting to it. A blank window on such an address therefore points at the host, the port or a certificate on an intermediate proxy, and not at a transport security setting inside the app. Checking the same address in Safari on the same machine confirms it in seconds.

If the window shows the app's own Load Failed page rather than a broken layout, the app is functioning and the address or the network is the problem. That distinction saves a lot of wasted configuration, because a Load Failed screen means the window, the engine and the pattern list all did their job and the response never arrived.

Check 8: knowing when to stop

Set a limit before starting, because an unmaintained tool has no upstream to escalate to.

The honest threshold is thirty minutes. If the checks above have not produced an answer in that time, rebuilding the app somewhere else is faster than continuing. Before deleting anything, copy down four things: the exact starting URL, every pattern in the Whitelist pane, the contents of any userscript, and the icon file. Those four are the whole configuration, and with them in hand recreating the app on any route takes a few minutes.

Which route to move to depends on one question, covered in the setup notes on Guide. If the app needs no link routing rules, a built-in route is enough and costs nothing. If the pattern list has real content in it, the replacement has to support the same idea, and the service specific notes on Supported services will show what each site requires before it is wrapped.

What to change first

Run checks 1 through 3 in order before opening any other pane, since launch architecture, signature state and the pattern list account for the large majority of reports. If the answer is in check 3 and the pattern list turns out to be doing real work, move that app to a maintained tool such as Kagemusha rather than tuning a build from 2018.