Troubleshooting

A site doesn't work properly

Ad blocking can break some sites: a video won't play, a login or comment section is missing, or the site says to turn off the ad blocker. Turn Block ads off in settings (⌘,), use the site, and turn blocking back on. Per-site exceptions are not available yet.

A site doesn't offer to sign in with a passkey

Passkeys (and security keys) in Litr need a copy of Litr signed with Apple's permission for browsers to use them, and Litr doesn't have that permission yet. Until it does, a site such as Google sees that passkeys aren't available and offers a password or a code instead. Litr can save and fill in that password for you (see Passwords).

Web apps can't use passkeys: each is its own app, and Apple's permission is given to Litr alone. Sign in with a password or a code there, or use the site in Litr.

YouTube shows ads again

YouTube changes often, and the script that blocks its ads needs updating to keep up. A future Litr release will fix it. Meanwhile, ads that start playing are still muted and skipped where possible.

A tab shows "This tab was unloaded to save memory"

A schedule unloaded it while you were looking at it. Click the message or press ⌘R to load it again.

A tab reloaded when I switched to it

It was unloaded to save memory. Litr keeps three tabs loaded by default and unloads background tabs after five minutes. To keep more tabs loaded, raise Tabs kept in memory or Unload background tabs after in settings. The page comes back at the same place, but unsaved form input can be lost.

Pages weren't blocked right after installing or updating

Litr prepares its ad block rules on the first launch after an install or a rule update, which takes a few seconds. Pages opened meanwhile load unblocked and reload when the rules are ready. If blocking still doesn't work, quit Litr, delete ~/Library/Application Support/Litr/ContentRules/, and start Litr again so it recompiles them.

The window looks transparent or hard to read

Turn off Glass edge in settings for solid chrome.

A web app says "can't be opened" or "Apple could not verify"

Web apps must be created on the Mac they run on. If you copied one from elsewhere, delete it and create it again with File → Create Web App…

Creating a web app says an app already exists

A web app with that name is already in ~/Applications. Choose another name, or remove the old app first (Settings → Web apps → Move to Trash).

The command palette closed by itself

It closes when you click outside it or switch to another app. Press ⌘K to open it again.

Pinned tabs or bookmarks were gone after updating to 1.5.0

On some Macs, Litr 1.5.0 couldn't read its saved tabs, so pinned tabs were missing, and bookmarks added in 1.4.1 were never saved. An older copy of Litr had marked the database as older than it was, and newer versions then stopped updating it.

Update to 1.5.1 or later. When it starts, Litr repairs the database, and your saved tabs and pinned tabs come back as they were when you last quit 1.4.1. Tabs opened while running 1.5.0 weren't saved, and bookmarks that were never saved can't be recovered: import them again from your other browser (Bookmarks → Import from Another Browser…); importing twice adds nothing twice.

If Litr ever can't update its database, a red strip under the toolbar says so. Quit Litr and open it again; if the strip comes back, let us know what it says.

An update failed

The About panel (Litr → About Litr) says what went wrong, and Try Again retries. Updates replace the app where it is, so Litr must be able to write to that folder; in /Applications that works for an administrator account. You can always download the newest version from elyracode.com/litr and replace the app by hand.

If an update says the download "is signed, but not by Litr's developer" or "doesn't match what the feed said", it was not installed. That is the safety check working. Try again later, or download from the website.

Restoring a backup

Litr copies its database once a day when it starts, and before an update changes it, into ~/Library/Application Support/Litr/Backups/, keeping the newest 5. Each is named after its day, such as litr-2026-09-27.db (…-before-v15.db for the copy taken before an update).

To go back to one:

1. Quit Litr.
2. In ~/Library/Application Support/Litr/, move litr.db, litr.db-wal and litr.db-shm somewhere safe.
3. Copy the backup you want there and name it litr.db.
4. Open Litr.

If Litr can't save to its database, a red strip under the toolbar says so; Show Backups there opens the folder.

Starting over

Quit Litr and delete ~/Library/Application Support/Litr/ to reset tabs, history, schedules and settings. Delete ~/Library/WebKit/no.gets.litr/ to sign out of all sites and clear site data.