This page is organized by what you’re seeing, not by what’s broken internally. If your problem isn’t here, please open a GitHub issue tagged bug and we’ll add it.

Known beta-period limitations

These are deliberate rough edges in the current beta. We mention them up front so they don’t surprise you. Each one links to its tracking issue.

API key problems

“Test connection” failed right after I pasted my key

Most common causes, in order:

  1. A space at the start or end of the key. Re-copy from Fish; don’t double-tap to select (which can include trailing whitespace). Try paste again.
  2. You copied only part of the key. API keys are long. Make sure your clipboard has the whole string.
  3. Your Fish account has no credit. Open your Fish dashboard and confirm a positive balance. Even a “test connection” costs a tiny fraction of a cent.
  4. The key was revoked or deleted on Fish. Go to your Fish dashboard → API keys and confirm the key still exists. If not, create a new one and paste it into Lucy.
  5. Fish is having an outage. Try again in a few minutes.

Lucy says “Missing Fish Audio API key” even though I saved one

Open Settings → API key and look at the status row. If it says Saved but Lucy still complains, hit Replace key and re-paste. This re-syncs the Keychain entry. Your previous key is overwritten, not stored alongside.

I want to remove my key entirely

Open Settings → API key → Replace key. Then close the dialog without saving a new one. The Keychain entry is deleted and Lucy returns to the first-run setup screen.

Voice and audio problems

Lucy spoke real-sounding words I didn’t type

This is a known characteristic of Fish Audio’s S2-Pro model: it occasionally hallucinates and produces fluent speech with the wrong words. It is not a Lucy bug — the same input through Fish’s own playground will sometimes do the same thing. It’s most common with custom or community-uploaded voices, very short inputs, and text containing names, abbreviations, or numbers.

What to do, in order:

  1. Tap Replay. Replay re-sends the same text to Fish, and because the hallucination is non-deterministic the second take is almost always clean. This is your fastest fix in the moment.
  2. Check the style cue field. Open Settings → Tuning → Voice style cue. If anything is in there, it gets prepended to every sentence as [cue] text, and Fish interprets it as a prosody instruction. Freeform sentences in this field will corrupt every output. If you didn’t mean to set it, clear the field. (#8 tracks adding guard rails so this is harder to do by accident.)
  3. Try a different voice. Switch to Lucy’s default voice as a control (Reference ID 11a3219f88c346929ecb671d695e5a97). If the default behaves well and your custom voice doesn’t, that voice is hallucination-prone and the fix is to pick a different one. Fish’s official showcase voices and high-popularity community voices tend to be much more reliable than recently-uploaded clones.
  4. Try the older model. Open Settings → Tuning → Model and switch from s2-pro to s2. The non-Pro model is less expressive but hallucinates much less.

The voice sounds wrong, slow, robotic, or has the wrong accent

You’re hearing the voice that the Reference ID in your active voice preset points at. Open Settings → Voices and either:

Voice quality varies dramatically across Fish’s library — that’s a Fish thing, not a Lucy thing. The default Lucy ships with is a reasonable starting point but is not the best Fish has to offer.

Volume is too low or too high

Two places to adjust:

  1. Lucy’s volume slider in Settings → Tuning. Note: Fish Audio’s volume parameter is an offset from default, not a percentage. Small values matter more than they look.
  2. Your system output volume. Lucy routes through whatever output device you pick.

Speech speed is wrong

Settings → Tuning → Speed. 1.0 is normal. 0.8 is noticeably slower; 1.2 is noticeably faster.

I hear myself in the meeting instead of Lucy

You probably routed Lucy’s output to your microphone’s monitor instead of through a virtual audio device. Recommended setup:

  1. Install BlackHole (free) or Loopback (paid).
  2. In Lucy → Settings → Output device, pick BlackHole / Loopback.
  3. In your meeting app (Zoom, Meet, etc.), pick BlackHole / Loopback as the microphone.
  4. To still hear Lucy yourself, create a multi-output device in macOS Audio MIDI Setup that contains both your speakers/headphones and BlackHole, and pick that as Lucy’s output instead.

Audio cuts off mid-sentence

If this happens consistently with one specific sentence, it may be a Fish-side issue with that voice + that text. Try splitting the sentence into two shorter ones.

If it happens randomly, it’s most often a network blip during the audio download. Lucy will mark the item as an error and move on; you can retype and try again.

Queue problems

Sentences are playing in the wrong order

They shouldn’t — the queue is strict FIFO. If you see this, please open an issue tagged bug with the exact sequence of what you typed.

I cleared the queue but the current sentence still played

That’s expected. Clear only removes items that are still waiting. To stop what’s currently being generated or played, use Stop. (See the Known Limitations note about Stop-during-generation above.)

The queue is getting really long and Lucy is sluggish

Quit and reopen Lucy to clear the session. Automatic pruning of completed items will arrive with the persistent history feature.

Cost problems

My Fish bill is higher than I expected

Things to check, in order:

  1. Long sentences cost more than short sentences, proportionally to character count. A 500-character paragraph costs roughly 5× a 100-character sentence.
  2. The “Test connection” button costs about a cent each time because it does a real tiny TTS request.
  3. Voice previews count if Fish renders them on demand. Most previews in Fish’s catalog are pre-rendered samples and likely don’t bill, but check Fish’s terms.
  4. Background or automated input. If something else on your machine was pasting or driving Lucy, that’s a likely culprit. Quit and relaunch.

I want a hard guardrail against accidental overspending

Until the Lucy-side daily cap ships, the strongest guardrail is the Fish account balance. Only top up the amount you’re willing to spend in a given period. When that balance is gone, Fish stops generating audio.

Installation problems

TestFlight says the build expired

TestFlight builds expire every 90 days. Email lucychapar@pm.me and we’ll send a new invite for the next build.

macOS says “Lucy can’t be opened because it is from an unidentified developer”

For the friends-and-family beta period, the macOS app may not be fully notarized. Workaround:

  1. Locate Lucy in Finder.
  2. Right-click (or Ctrl-click) → Open.
  3. macOS shows a warning; click Open.

You only have to do this once per install.

The shipping macOS build will be Developer-ID signed and notarized so this prompt disappears.

Accessibility

Lucy is a typing-to-speech app for people who can type comfortably. It is not designed around screen-reader use and does not include VoiceOver / screen-reader integration. Adding that integration is not on the current roadmap.

What does work today:

If you rely on a screen reader as your primary way to use your device, Lucy is unlikely to be the right tool, and we’d point you toward established AAC apps designed around that workflow instead.

Reporting a bug we should know about

If your problem isn’t on this page, please open a GitHub issue tagged bug with:

For security disclosures or other private matters, email lucychapar@pm.me instead.