Help

Troubleshooting

Common problems and fixes. The quoted messages are what the app shows in English.

#Install and first launch

Linux: on Ubuntu 23.10 and later, the AppImage can stop at launch with a sandbox error, because AppArmor restricts the user namespaces Electron's sandbox uses. Install the .deb instead.

#Screen or window capture fails (macOS)

Message: Recording the entire screen or another window requires macOS Screen Recording permission.

  1. In the Recording Target dialog, click Open System Settings.
  2. Privacy & Security → Screen & System Audio Recording: turn on Ferret.
  3. Restart the app, then click Check Again.

Recording the Built-in Browser needs no permission.

Running from source on macOS, pnpm dev launches a renamed, ad-hoc signed copy of Electron that is also called Ferret (scripts/prepare-dev-electron.mjs), so it appears as a separate Ferret entry in these lists. The first time it runs, macOS asks again for Screen Recording and Microphone access. It doesn't ask again after that. Development builds use a mock keychain (--use-mock-keychain), so there is no Keychain prompt: cookies and keys saved in a dev build are encrypted with a fixed key, not the real Keychain. Set ADE_DEV_REAL_KEYCHAIN=1 to use the real Keychain.

#Microphone does not open

Message: Couldn't open the microphone. Check the permission in your OS settings.

  • macOS: System Settings → Privacy & Security → Microphone, then turn on Ferret.
  • Windows: Settings → Privacy & security → Microphone, then allow desktop apps.

Without a mic, pen circles still create findings, but they carry no spoken request.

#The other side of a meeting is not recorded

When Record the other side too is on and your computer's audio can't be recorded, Ferret shows one of these warnings and keeps recording your microphone, the video, and the pen.

  • Ferret isn't allowed to record system audio. (macOS): turn on Ferret in System Settings → Privacy & Security → Screen & System Audio Recording, quit and reopen Ferret, then start a new recording.
  • Recording the other side needs macOS 14.2 or later.: update macOS. Until then only your microphone is recorded.
  • Windows didn't allow access to system audio. or no audio output device was found.: enable speakers or headphones in Settings → System → Sound (Windows) or connect them, then start a new recording.
  • system audio isn't available. (Linux): install PulseAudio, or pipewire-pulse if you use PipeWire.
  • Stopped recording the other side: the audio output device changed or was disconnected.: the rest of the recording continues without the other side. Use Record more to capture the rest.

If the other side's words also appear as yours, your microphone is picking up your speakers. Use headphones.

#No on-device model / whisper-cli not found

Message: No on-device transcription model found. Audio will be saved, and only pen findings will be processed.

Download a model in Settings, or choose an existing ggml-*.bin. If Settings says whisper.cpp (whisper-cli) was not found, install it (instructions), make sure it is on PATH, and reopen Settings. Packaged apps launched from Finder or Explorer may not see your shell's PATH, so install to a standard location such as Homebrew's.

A model download that fails its sha256 check is discarded. Retry it.

#Terminal: node-pty could not be loaded

This happens when running from source and node-pty was built for a different Node or Electron ABI.

pnpm rebuild:native

#Agent not found / Send to Agent doesn't send

  • Claude Code: Not found (or another built-in agent's name), or command not found: … in the terminal for an agent you added: the CLI is not installed or not on PATH. Ferret starts built-in agents only from an absolute path in a PATH folder outside the project, never from the project folder. Check that the command works in your normal terminal, use Install in Settings → Agents, or set an absolute path as that agent's Command.
  • The agent is waiting for confirmation. Respond in the terminal, then send. Answer the agent's prompt first.
  • The agent's input isn't ready yet. Wait for the agent to finish starting.
  • The text was entered but not sent. Press Enter in the terminal.
  • Open a terminal first.
  • Can't parse launch arguments: Unclosed quote. Fix the quoting in the agent's arguments.
  • Put … in the launch arguments, not in the command. or Write … in the launch arguments without quotes or backslashes. Write that flag as plain text in the agent's arguments. To start agents without permission prompts, turn on Start agents without permission prompts in Settings → Agents.

#Recording won't start

  • Open a project folder first.
  • Open a URL to review first.
  • The page didn't load. Open a URL that displays, then record. Check that the dev server is running. Can't connect to the server means nothing is listening on that port.

#OpenAI key or endpoint not set

No OpenAI API key is set… or The transcription endpoint (Base URL / model) isn't set…: add it in Settings, or switch to On device (free). The audio of that recording is already saved.

#GitHub errors

  • GitHub CLI (gh) not found. Install gh.
  • Not signed in to GitHub. Settings → Service CLIs.
  • No origin remote. or origin isn't a GitHub repository. Check git remote -v.
  • Repository not found, or you don't have access. Check gh auth status and GH_TOKEN.

#Report a bug

Open an issue at github.com/JapanMarketing-Dev/ferret/issues (opens in a new tab) with your OS, the app version (footer → Updates), and steps to reproduce. Don't attach .ferret/ contents that contain private screens.

Edit this page on GitHub (opens in a new tab)