Common Issues
Quick fixes for the problems that come up most. For error messages from a model or provider, see Provider Errors.
It Does Not Open
If Fluent does not open with the global or action shortcuts:
- Check the shortcut: Settings → Shortcuts lists the Smart Panel's (⌥Space by default) and every action's
- Check that Fluent is allowed in System Settings → Privacy & Security → Accessibility. Shortcuts start working as soon as you allow it, with no restart. If Fluent isn't in that list, click Authorize in Accessibility in Fluent's setup guide (or Open Settings under Voice's warning): it adds Fluent there for you to switch on
- Check that the app you're in isn't in Settings → Blacklist
- Make sure the shortcut is not already used by another app. If unsure, try a different one
- Check your license: shortcuts work only while your trial or license is active. If the trial has ended, choose Activate… in Fluent's menu bar menu
The chat window has no shortcut until you set one under Chat UI shortcut in Settings → Shortcuts. Until then, open it with Toggle Chat UI in the menu bar, or press ⌘E in the Smart Panel.
No Selected Text
If Fluent opens but the current selection is missing, check Accessibility permissions first.
Make sure Fluent is enabled under Privacy & Security → Accessibility. Then test the same selection in a simple app such as Notes. This tells you whether the issue is global or specific to one app.
If Show text selection as attachment is on in Settings → Smart Panel, look for the selection as an attachment in the prompt.
If selection capture still fails in every app, quit and reopen Fluent, then test again.
No Insertion
If an action runs but nothing is inserted back into the current app:
- Confirm that the target field is a normal editable text field
- Confirm that the action has Auto insert turned on, if that is the expected behavior
- Test the same action in Notes or another simple editor
Turn on Show loading cursor (for auto insert actions) in Settings → Smart Panel to see a spinner by the pointer while such an action is still working.
If the action inserts correctly in a simple app but not in the original one, the issue is usually the target app, not Fluent itself.
Missing Context
If browser or app context is missing, open Settings → Context first.
Check these items:
- Enable app context
- Enable browser context
- Automatically attach active app or Automatically attach active tab if you expect automatic attachment
- Use selected text only if Fluent should ignore the surrounding app and page when text is selected
For browser context, the page in the front tab needs no browser setting: Fluent reads it through Accessibility. If it arrives as a title and an address with no content, check that Fluent is allowed in System Settings → Privacy & Security → Accessibility. Safari and Chrome-style browsers also need Automation for the tab's address and the tab list (see AppleScript Issues below).
A tab in the background needs browser scripting: Safari and Chromium-style browsers need Allow JavaScript from Apple Events for it and for browser automation workflows. Firefox has no such setting, so bring the tab you want to the front.
If a Firefox tab never shows up, check that Firefox's accessibility isn't turned off: hardened setups such as arkenfox set accessibility.force_disabled, which hides the page from Fluent.
AppleScript Issues
macOS asks for Automation access ("Fluent wants to control…") the first time you use Fluent with an app such as your browser, not at launch. If you clicked Don't Allow, turn Fluent back on for that app in System Settings → Privacy & Security → Automation.
If Fluent never asks at all, the most common reason is a cracked version of Fluent that was quarantined by macOS Gatekeeper.
Another possible reason: check if you have AU components in your user folder. macOS osascript, which is responsible for AppleScript interaction, has a bug that might prevent Fluent from asking for Automation permissions due to the AU plugins folder being present in the user folder.
Model Empty Response
When a request fails, Fluent shows the provider's error in the reply, even when the failure comes partway through an answer. A brief hiccup at NanoGPT or another OpenAI-compatible provider, before the answer starts, is retried once on its own.
An empty reply, or one that loads for too long, usually comes from the model itself:
- The model is too small for the request. Apple Intelligence and tiny models like Qwen3 0.6B handle short questions and a few paragraphs. They struggle with attached files and browser or app context, and Apple Intelligence gets no tools at all.
- "Use structured JSON". Some models don't support it, and some struggle with it through third-party providers. In Settings → Models, click the sliders button on the model's row and turn it off. You can also turn it off for a whole custom provider.
- Censoring. Models that censor a lot can fail silently. Check whether your request contains a question or data the model might refuse.
Request Stops When The Panel Closes
Turn on Keep requests running in background in Settings → Smart Panel. Closing or hiding the Smart Panel then lets the answer finish: the menu bar shows it running, and a notification arrives when it's done.
It is on for new installs, but may be off if you used Fluent before version 2.0.
Dictation Doesn't Work
| What you see | What to do |
|---|---|
| Nothing happens when you press the shortcut | Turn on Enable voice dictation in Settings → Voice, and check Dictation shortcut in Settings → Shortcuts (⌃⌥Space by default) |
| A red warning icon next to Enable voice dictation | Click it. If microphone access is denied, allow Fluent in System Settings → Privacy & Security → Microphone |
| Fluent doesn't hear you | Choose the right Microphone in Settings → Voice |
| Accessibility access required in Voice settings | Allow Fluent in System Settings → Privacy & Security → Accessibility, so it can type into other apps |
| A progress bar next to Speech model | The first time, Fluent downloads the speech model, and a polish model unless the preset is As dictated. Stay online until a green checkmark appears |
| The shortcut opens Ask Fluent instead of typing | Click into a text field first. In a field, set When dictating in a text field to Dictate |
| Words come out in the wrong language | Dictation expects your Native language from Settings → General. To speak other languages, choose a multilingual Speech model and turn on Auto-detect spoken language in Settings → Voice |
| A model you downloaded shows as not downloaded again | Local models live in your Documents folder. If it syncs to iCloud with Optimize Mac Storage, macOS can move them off your Mac, and Fluent downloads them again |
See Voice for how dictation works.
Memory Doesn't Learn
| What you see | What to do |
|---|---|
| Memory does nothing | Turn on Memory in Settings → Integrations. It may be off if you used Fluent before version 2.0 |
| "Remember…" saves nothing | Use a model that can use tools: Apple Intelligence can't save memories, and neither can a model with Use tools off (the sliders button on its row in Settings → Models) |
| Details you mention in passing aren't kept | Turn on Save new memories automatically in the gear in Settings → Memory. Without it, Fluent saves only when you ask |
| Saved memories aren't used | Turn on Automatic retrieval in the gear in Settings → Memory, and check that the item's switch is on in Settings → Memory |
| An action never uses Memory | Turn on Use automatic memory under Integrations & Memory in the action's editor |
| A file says Apple Intelligence doesn't support this item's language | Right-click it, choose Learn Again… and pick another model, or change the Learning model in the gear in Settings → Memory |
| Files wait to be learned | Apple Intelligence may still be downloading its model. Fluent learns them once it's ready |
| A password or card number wasn't saved | By design: Fluent never saves secrets, even when you ask |
It Looks Like A Provider Error
If the request fails with messages about API keys, billing, missing models, rate limits, sign-in or a subscription's usage limit, see Provider Errors.
Those problems usually come from the selected provider, not from Fluent itself.