Handbook/docs/TROUBLESHOOTING.md at master · ECRomaneli/Handbook · GitHub
Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
152 lines (95 loc) · 5.52 KB

TROUBLESHOOTING.md

File metadata and controls

152 lines (95 loc) · 5.52 KB
Raw

Troubleshooting

Common issues and solutions for Handbook.

Table of Contents

macOS Security Warning

Handbook is not code-signed, so macOS may block it from opening with a message like "Handbook can't be opened because it is from an unidentified developer".

Remove Quarantine Flag

After moving Handbook to the Applications folder, open the Terminal and run:

xattr -dr com.apple.quarantine /Applications/Handbook.app

This removes the quarantine flag that macOS adds to downloaded apps, allowing Handbook to open normally. If this option doesn't work, try the next method.

Via System Settings

Alternatively, you can allow the app through macOS settings. The steps depend on your macOS version. For the most up-to-date instructions, refer to the official Apple Support Guide.

macOS Sonoma 14+ / Sequoia 15+

  1. Open Apple menu > System Settings.
  2. Click Privacy & Security in the sidebar (scroll down if needed).
  3. Under Security, find the message about Handbook being blocked and click Open.
  4. Click Open Anyway.
  5. Enter your login password and click OK.

This button is available for about an hour after attempting to open the app.

macOS Ventura 13 or Earlier

  1. Open the Applications folder in Finder.
  2. Hold Ctrl and click the Handbook icon.
  3. Select Open from the context menu.
  4. Click Open on the security warning dialog.

After these steps, the warning will not appear again.

If the Open button doesn't appear the first time, try the process twice.

Alternative: Build from Source

For full code integrity assurance, you can build Handbook from source.

Tray Icon Not Visible

Windows

The tray icon may be hidden by default:

  1. Click the upward arrow (^) in the system tray area (bottom-right corner).
  2. Find the Handbook icon in the expanded area.
  3. Drag it to the main tray area to pin it for permanent visibility.

Linux

Some desktop environments may not show tray icons by default. Ensure your desktop environment supports the system tray (also known as StatusNotifierItem or AppIndicator).

For GNOME-based desktops, you may need to install an extension like AppIndicator Support.

Page Not Loading

  • Check the URL — Ensure the URL is correct and accessible in a regular browser.
  • Check your network — Verify your internet connection is active.
  • Session conflict — If multiple pages share a session and one redirects, it may affect others. Try using a different Session ID.
  • Clear session data — Remove the page, create it again with a new Session ID to start fresh.

Shortcuts Not Working

Global shortcuts may fail if:

  • Another app has registered the same shortcut. Try a different key combination.
  • OS permissions — On macOS, ensure Handbook has accessibility permissions: System Settings > Privacy & Security > Accessibility.
  • The shortcut is invalid — Use Electron-compatible accelerator format (e.g., CmdOrCtrl+Shift+H).

Linux (Wayland)

On Wayland sessions, Handbook runs through XWayland and registers the global shortcut using the desktop's Global Shortcuts portal (xdg-desktop-portal):

  • GNOME shows a confirmation dialog the first time the shortcut is registered. The shortcut only works after you accept it.
  • The key combination can be changed afterwards in your desktop's shortcut settings. The key shown in Handbook's preferences may then differ from the one actually in use.
  • Linux packages only — the portal identifies the app by its installed com.github.ecromaneli.handbook.desktop file. When running from source or from an unpacked build, the portal may reject the shortcut.
  • AltGr combinations are not supported by the portal.

Opacity Not Working (Linux)

Window opacity (focus/blur transparency) is not supported on Linux due to compositor limitations on most desktop environments. The opacity settings will be ignored.

Permission Issues

If a page isn't working correctly (e.g., can't access clipboard, camera, or microphone):

  1. Go to Settings > Permissions.
  2. Find the relevant session and URL.
  3. Check if the permission is set to Deny.
  4. Change it to Allow or Ask.

You can also revoke all permissions for a URL or session and re-grant them.

Sync Issues

GitHub Gist Sync

  • Token errors — Ensure your GitHub personal access token has the gist scope.
  • Gist not found — Verify the Gist ID is correct. Leave it empty to create a new one.
  • Push fails — Check your internet connection and token validity.

Local File Import

  • Invalid file — Ensure the file is a valid JSON exported by Handbook.
  • Missing pages — The import replaces your current configuration. Export a backup before importing.

Getting Help

If your issue isn't listed here:

  1. Check the GitHub Issues for similar reports.
  2. Open a new issue with:
    • Your OS and version
    • Handbook version
    • Steps to reproduce
    • Expected vs. actual behavior
    • Screenshots, if applicable