Troubleshooting
Fixes for common Neru problems, listed by symptom. Each entry gives the cause and the fix. Linux host problems are in Linux setup, and desktop-specific ones in Linux desktops.
Quick diagnosis
Section titled “Quick diagnosis”Run these three first. Most problems show up in one of them.
neru status # is the daemon running?neru doctor # per-component health, works even if the daemon is downneru hints # does a mode open from the CLI?If the CLI cannot reach the daemon, start it with neru launch. For a bug
report, paste the output of neru doctor --json, which holds every check in
one object. For more detail, see Collecting diagnostics.
Installing
Section titled “Installing”“Cannot open Neru because the developer cannot be verified”
Section titled ““Cannot open Neru because the developer cannot be verified””macOS quarantined the download. Remove the flag, then open Neru:
xattr -cr /Applications/Neru.appopen -a Neru“command not found: neru”
Section titled ““command not found: neru””The install directory is not on your PATH. The install script prints which
directory it used. Add it in your shell’s rc file, for example
export PATH="$HOME/.local/bin:$PATH".
Homebrew install or upgrade fails
Section titled “Homebrew install or upgrade fails”Run brew update && brew reinstall --cask neru.
“profile.ps1 cannot be loaded because running scripts is disabled”
Section titled ““profile.ps1 cannot be loaded because running scripts is disabled””Windows blocks the tab completion the installer added to your PowerShell profile. Allow signed scripts for your user, then open a new window:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedTo drop the completion instead, delete the two lines under
# neru shell completion (managed by install.ps1) in the profile.
“error while loading shared libraries”
Section titled ““error while loading shared libraries””On Linux a runtime library is missing, or Fedora names tesseract differently. See Linux setup.
Permissions
Section titled “Permissions”Neru does nothing on macOS
Section titled “Neru does nothing on macOS”Neru needs Accessibility permission. See
Grant permissions. If neru doctor still reports
an error, which often happens after an upgrade, remove Neru from the
Accessibility list, add it again, and restart the daemon.
Modes do not open while a password field is focused
Section titled “Modes do not open while a password field is focused”macOS secure input is on, and it blocks every app from reading keys, including Neru. Click out of the password field and try again.
Hints and grids
Section titled “Hints and grids”No hints or grids appear
Section titled “No hints or grids appear”- Run the quick diagnosis.
- Check the permissions.
- Check the app is not in
excluded_apps. - Try another app, to tell an app problem from a Neru problem.
No hints on my other monitor
Section titled “No hints on my other monitor”Neru draws hints only on the display the cursor is on. Move the cursor to the focused window first:
[hotkeys]"Primary+Shift+Space" = ["action move_mouse --window", "hints"]Or use a window manager that makes the cursor follow focus.
No hints in a browser or Electron app
Section titled “No hints in a browser or Electron app”- macOS: Neru detects Chromium, Firefox, WebKit and Electron from the app
bundle. With file logging and
debug logging on, show hints in the browser, then
run
grep bundle_type ~/Library/Logs/neru/app.log. An emptybundle_typeon the browser’sBuilt accessibility treeline means Neru did not detect it, so open an issue with its bundle ID. - Linux: start Chromium and Electron apps with
--force-renderer-accessibility.
An element I can see has no hint
Section titled “An element I can see has no hint”Run neru roles --explain to see which roles your config hints. If you changed
hints.clickable_roles, restore it from the
default config
and run neru config reload. If the default misses it too, open an issue.
Hints appear on things I cannot see
Section titled “Hints appear on things I cannot see”Neru may be hinting invisible elements such as row, list_item and cell. Copy the
clickable_roles list from the
default config,
remove those roles, and run neru config reload.
Hints or grids are misaligned
Section titled “Hints or grids are misaligned”On Wayland, hints in native apps depend on the compositor reporting window positions, and some do not. See Linux desktops.
Anywhere else this is a bug. Turn on file logging and debug logging, reproduce it, and open an issue with the log, a screenshot, your OS version, and the app name and version.
No hints in the menu bar or Dock
Section titled “No hints in the menu bar or Dock”Both are off by default on macOS. Under [hints], set
include_menubar_hints = true and include_dock_hints = true.
To hint another app’s menu bar item, add its bundle ID to
additional_menubar_hints_targets. Your list replaces the default one, so copy
the defaults from the
default config
and add yours:
[hints]additional_menubar_hints_targets = [ "com.apple.TextInputMenuAgent", "com.apple.controlcenter", "com.apple.MenuBarAgent", "com.apple.systemuiserver", "com.y3owk1n.neru", "com.example.MenuBarApp", # your app]Hotkeys
Section titled “Hotkeys”A hotkey does nothing
Section titled “A hotkey does nothing”- Run the mode from the CLI, such as
neru hints. If it opens, the hotkey is at fault. - Check the daemon is running with
neru status. - Check the app is not in
excluded_apps. - Run
neru config validate, and check the binding against the hotkey syntax. - Try another chord, in case another app owns this one.
On Linux, see Bind your first hotkey first.
A hotkey works in some apps but not others
Section titled “A hotkey works in some apps but not others”The app is in [general].excluded_apps, so remove it. Entries name apps by
app identity.
A hotkey clashes with a system shortcut
Section titled “A hotkey clashes with a system shortcut”Change the system shortcut, in System Settings > Keyboard > Keyboard Shortcuts on macOS, or move Neru’s binding:
[hotkeys]"Primary+Shift+Space" = "__disabled__""Ctrl+Alt+Space" = "hints"To drive Neru from another hotkey tool such as skhd, see Recipes.
Keys type the wrong characters
Section titled “Keys type the wrong characters”Neru reads keys through your OS keyboard layout. Check the layout is selected
in your OS. Neru cannot resolve some custom layouts on its own, so set
kb_layout_to_use to the one you want,
copied from the keyboard_layouts row of neru doctor.
Neru re-registers global hotkeys after a layout switch. On Windows this can take up to a second. If hotkeys still fail, restart the daemon.
A CJK input method misbehaves
Section titled “A CJK input method misbehaves”Neru works with input methods such as Pinyin and Wubi. Check the method is installed and active in your OS, and on macOS that Neru has Accessibility permission.
Hint search and vim mode read keys before the input method does. To find text
in another script, type its romanization, so nihao finds 你好.
Performance
Section titled “Performance”Hints are slow to appear
Section titled “Hints are slow to appear”The usual causes, most likely first:
- Too many entries in
hints.clickable_roles. - Debug logging left on.
- A system under load.
Neru uses a lot of CPU
Section titled “Neru uses a lot of CPU”Check with top -pid $(pgrep neru) on macOS, top -p $(pgrep neru) on Linux,
or Task Manager on Windows. Look for errors in the log
and restart the daemon. If it happens again, open an
issue with the log.
The daemon
Section titled “The daemon”The CLI cannot reach the daemon
Section titled “The CLI cannot reach the daemon”Run neru doctor, then neru launch, then neru status. If it still fails on
macOS or Linux, a stale socket file is in the way. Delete the file at the
endpoint path, which the daemon also prints at
startup, then run neru launch again.
The daemon exits on startup
Section titled “The daemon exits on startup”It is usually a config error, and neru config validate names the key. To rule the
config out, move config.toml aside and run neru launch in a terminal. On
macOS it asks whether to create a config, with Create Config,
Use Defaults (No Config) and Quit, and Windows asks the same with Yes,
No and Cancel. Choose Use Defaults. Linux shows a notice and continues.
Neru then runs on built-in defaults and prints why it exits.
“version mismatch” after an upgrade
Section titled ““version mismatch” after an upgrade”The running daemon is still the old binary. Restart the daemon.
“client needs protocol N, daemon speaks M”
Section titled ““client needs protocol N, daemon speaks M””A program built on the Go client, or a script that sends protocol over the
socket, asked for a newer protocol than
the daemon speaks. This happens after a downgrade, or when the program was
updated and the daemon was not. Upgrade Neru and
restart the daemon, or build the program against the
client of the release you run.
The daemon stops responding or will not quit
Section titled “The daemon stops responding or will not quit”Force it to quit and start it again:
pkill -9 neru && neru launch # macOS, Linuxtaskkill /IM neru.exe /F; neru launch # Windows PowerShellIf neru launch still fails, clear the stale socket as in
The CLI cannot reach the daemon.
Config
Section titled “Config”My config changes do nothing
Section titled “My config changes do nothing”Neru does not watch the file. See
Apply your changes. Run
neru config validate, then neru config reload. If the file has one error,
Neru rejects the whole reload and keeps the previous config. To check which
file the daemon read, see
Where Neru looks for the file.
A misspelled key is not an error. Neru skips it, and neru config validate
names it in a warning, so check its output for not a Neru option. The daemon
also logs each one as a Configuration warning at launch and on every reload.
An editor that reads the schema
flags it as you type.
An option that does nothing on your OS is not an error either. The
platform_support row of neru doctor
lists each one.
A value set with neru config set wins over your file. See
How the layers combine.
neru config reset <key> removes it.
“configuration parse config file failed”
Section titled ““configuration parse config file failed””The file is not valid TOML, or a value has the wrong type. At launch and in
neru config validate, the message follows Configuration validation failed:
and names the line. Common causes:
- a key containing
+without quotes - a string where a number belongs, such as
max_depth = "50"
A value Neru refuses prints configuration validate configuration failed
instead, with the key and the reason. Common causes:
- a color without its leading
# - a hotkey bound to an empty string, where
__disabled__was meant
Specific apps
Section titled “Specific apps”Hints are misaligned or missing in Adobe apps (macOS)
Section titled “Hints are misaligned or missing in Adobe apps (macOS)”Add roles for the app, named by its bundle ID.
[[hints.app_configs]]bundle_id = "com.adobe.illustrator"additional_clickable_roles = ["static_text", "image"]ignore_clickable_check = trueNo hints in Mission Control (macOS)
Section titled “No hints in Mission Control (macOS)”Dock hints include Mission Control. Set include_dock_hints = true and
detect_mission_control = true under [hints] to get hints on the current
desktop’s windows. The desktops in the Spaces bar get hints once the bar
expands, so move the pointer to the top edge before showing hints.
The cursor lands in the wrong place under Accessibility Zoom (macOS)
Section titled “The cursor lands in the wrong place under Accessibility Zoom (macOS)”With System Settings > Accessibility > Zoom zoomed in, Neru places the cursor exactly and pans the zoomed view to the target. If the cursor misses or the view does not follow, open an issue with your macOS version and zoom factor.
Collecting diagnostics
Section titled “Collecting diagnostics”How to restart Neru, where its log is, and how to make the log say more. Use these for any problem above, or before filing a bug.
Restart the daemon
Section titled “Restart the daemon”neru stop only pauses Neru and leaves the process running. To restart it:
neru services restart # if you installed the login servicepkill neru && neru launch # macOS, Linuxtaskkill /IM neru.exe; neru launch # Windows PowerShellLog file locations
Section titled “Log file locations”By default the daemon logs only to the terminal that started it. To write a
log file, set disable_file_logging = false under [logging] and
restart the daemon.
| Platform | Log file |
|---|---|
| macOS | ~/Library/Logs/neru/app.log |
| Linux | ~/.local/state/neru/log/app.log |
| Windows | %LOCALAPPDATA%\neru\log\app.log |
When the login service runs Neru, a
crash or a failure before the log file opens is not in app.log:
- macOS: read
~/Library/Logs/neru/daemon.err.log, where the service sends the daemon’s stderr. - Linux: run
journalctl --user -u neru. The journal holds everything the daemon printed, with or without file logging.
[logging].log_file overrides the path. Each line is JSON, so
grep ERROR ~/Library/Logs/neru/app.log finds failures Neru could not recover
from, and grep WARN finds ones it worked around. Rotation is in the
logging reference. To start a fresh
log, delete the file and restart the daemon.
Enable debug logging
Section titled “Enable debug logging”Neru logs key routing, overlay redraws and hint filtering only at debug.
Set log_level = "debug" under [logging] and
restart the daemon. Set it back to "info" afterwards,
because debug logging slows hint activation.
| Log message | Meaning |
|---|---|
Found usable accessibility tree | The app’s accessibility tree was found (macOS) |
Hints mode activated | The hint overlay is up, with the hint count when available |
Clickable element collection was slow | Reading the accessibility tree took longer than expected |
Failed to show hints | Collecting elements or drawing hints failed. Check permissions and excluded_apps |
Mode activation refused | A mode did not start. The error field says why: secure input, an excluded app, the mode disabled, or Neru stopped |
Getting help
Section titled “Getting help”Search the issues, then open one
with the bug-report form. It asks for neru doctor output, your OS version,
neru --version, the app, the relevant config, and the
log.
Emergency reset
Section titled “Emergency reset”- Force Neru to quit, as in The daemon stops responding.
- Remove it as Uninstallation describes.
- Reinstall and run
neru launch. - On macOS, grant Accessibility permission again.