Troubleshooting

Solutions to the problems users hit most often. If yours isn’t here, grab logs and file an issue — that’s how the browser gets better.

First steps for any problem

1. Reproduce in a private tab

   Extensions and site data cause many issues. If it disappears in private mode, an extension or cached state is the culprit.

2. Toggle extensions off

   Disable all extensions, then re-enable one at a time.

3. Clear site data

   Settings → Privacy → Clear data for the affected site.

4. Check for an update

   Many bugs are already fixed in the latest release.

Video won’t play or download

• Grabber chip doesn’t appear — the stream may be DRM-protected (Omni won’t and can’t strip DRM) or the site uses a transport the sniffer doesn’t recognize yet.
• Playback stutters — lower the quality in the player, or disable other extensions that hook media.
• Download stalls at a percentage — HLS segment downloads resume automatically; if it’s truly stuck, cancel and restart. Check free storage.
• No audio extraction — FFmpeg downloads on first use. Make sure you were online the first time you tapped “Extract audio”.

An extension broke a site

Content blockers and script extensions can over-block. To isolate:

# In Omni:
# 1. Open the Extensions panel
# 2. Toggle off the suspect extension
# 3. Hard-reload the page (Ctrl+Shift+R)
# 4. If fixed, report the site to the extension author
#    and/or file an Omni issue with the URL

Crashes on launch

• After an update — a corrupted session restore can crash on start. Clear Omni’s cache (Android Settings → Apps → Omni → Storage → Clear cache), which preserves your data but resets the restore point.
• On a specific device — GeckoView needs a reasonably modern GPU driver. Very old or heavily modified ROMs may not be supported.
• Repeated crashes — Omni has a crash-loop guard that resets the last session after repeated failures. If you’re stuck, clear cache as above.

Downloads fail

• Permission denied — grant Storage/Files access in Android Settings → Apps → Omni → Permissions.
• Vault save fails — the vault needs biometric/PIN enrolled. Set one up in Settings → Privacy → Vault.
• “Insufficient space” — streams need headroom for segment assembly; keep at least 2× the file size free.

Slow performance

• Too many open tabs — enable smart tab grouping or close old ones.
• A heavy extension (some ad-blockers with huge lists) — try Omni’s built-in blocker instead.
• Low-end device — disable dynamic color and reduce the UI scale in Settings → Appearance.

Filing a great bug report

Open an issue at github.com/REBEL-ROOT/omni-browser/issues using the bug template. Include:

• Omni version (Settings → About) and Android version
• Device model and ABI
• Steps to reproduce, and what you expected vs. what happened
• The URL (if not sensitive) and which extensions are active