DocsHelp
Troubleshooting
Fixes for the most common problems with starting the app, macOS and Windows warnings, the extension connection and online search.
The app won’t start
- If you see “Nishio could not start”, click “Open logs folder”. The log files there describe what went wrong; keep them if you report the problem.
- If “A background service stopped unexpectedly” appears, choose “Restart Nishio”.
- A red banner saying “Could not reach the local service. Start Nishio and retry.” means the window lost contact with the local service; use the refresh button, or quit and reopen the app.
- On Linux, if the AppImage does not open, check that it is executable (chmod +x). Some distributions also need FUSE support for AppImages; the .deb package is an alternative.
macOS and Windows warnings
- Keychain prompt on first launch: choose “Always Allow”. If you deny it, saved keys may not be readable later (“Saved keys on this computer could not be decrypted”); remove the key in Settings & team and add it again.
- Gatekeeper: if macOS refuses to open the app because it cannot verify it, open System Settings → Privacy & Security and click “Open Anyway”, or Control-click the app and choose Open.
- Windows SmartScreen: click “More info”, then “Run anyway”. The Windows build is not code-signed yet.
The extension can’t connect
- The app uses 127.0.0.1:4310 when that port is free. If another program is already using it, Nishio picks a different free port, and the extension’s Local API address must point to that port. The app does not display the alternative port yet, so the simplest fix is to quit the program using port 4310 and restart Nishio.
- “Optional backend sync needs pairing again”: the one-hour permission ended or the browser was closed. Create a new one-time code and pair again.
- “Open a YouTube home, search, watch, Shorts or channel page”: the extension only reads YouTube. If you just installed it, reload the YouTube tab and wait for the page to finish rendering.
Online search and quota
- “Official online search needs your own YouTube API key”: add a key in Settings & team → YouTube API accounts. Everything else keeps working without it.
- “That doesn’t look like a YouTube API key”: copy the full key from Google Cloud → Credentials.
- “This project has reached its local budget or YouTube rate limit”: wait for the reset at midnight Pacific or request more quota from Google. Saved data stays available.
Start over
- Create a backup (Settings & team → Create verified backup) and copy it somewhere safe.
- Quit Nishio.
- Rename or delete the data folder: ~/Library/Application Support/Nishio on macOS, %APPDATA%\Nishio on Windows, ~/.config/Nishio on Linux.
- Open Nishio again. It starts fresh with the setup screen.
Deleting the folder deletes everythingThe data folder holds your accounts, research, reports and encrypted key. Renaming it instead of deleting it keeps a copy you can go back to.