Troubleshooting ReplyRabbit
Most ReplyRabbit problems come down to one of three things: a missing or wrong API key, using a provider your plan tier does not allow, or a stale FreeScout cache. Work through the matching section below, where each issue lists the symptom first and then the fix.
No draft is generated
Symptom: you open a conversation, but no AI draft appears and nothing seems to happen.
Fix: open the mailbox's ReplyRabbit settings (Mailbox > Settings > ReplyRabbit) and confirm a provider is selected and its API key is set. On the Free tier the only available provider is OpenAI, so if you picked a different one, switch back to OpenAI or upgrade. Then check that ReplyRabbit is enabled for the mailbox you are working in, since drafts only generate for enabled mailboxes.
Invalid API key or provider error
Symptom: you see an error mentioning an invalid key, authentication failure, or a provider that cannot be reached.
Fix: re-check the key for typos and stray spaces, confirm it is the key for the provider you actually selected (an OpenAI key will not work with Anthropic), and make sure the key still has credit and access on the provider's dashboard. A key with no remaining balance or revoked access produces the same error.
Errors after upgrading PHP
Symptom: after a server upgrade (for example, to Ubuntu 26.04 with PHP 8.5), Test connection fails or background jobs stop, and the FreeScout log shows messages ending in is deprecated since 8.5.
Fix: keep ReplyRabbit and your other modules up to date from Manage > Modules, then run php artisan freescout:clear-cache and php artisan queue:restart. ReplyRabbit supports PHP 8.0 through 8.5. See Fix "deprecated since 8.5" errors in FreeScout to find which module a message comes from.
The ReplyRabbit menu is missing
Symptom: ReplyRabbit does not appear in the FreeScout menus or settings after installing it.
Fix: first make sure the module is activated under Manage > Modules. Then clear the cache from your FreeScout root:
php artisan freescout:clear-cacheIf it is still missing, check the user's permissions: a user without access to the relevant mailbox or admin settings will not see the ReplyRabbit options.
Drafts stopped after a while
Symptom: drafts worked at first, then stopped generating later in the month.
Fix: the Free tier allows 10 drafts per month. Once you hit that limit, drafts pause until the next month. Pro and Team have no draft limit. On any plan, drafts also pause if the mailbox's Monthly Token Budget is used up, so check that setting too (0 means no budget).
Prompt caching does not change the monthly token count
Symptom: repeated drafts seem eligible for provider prompt caching, but ReplyRabbit's token usage still shows the full input and output total.
Fix: this is expected. ReplyRabbit keeps monthly budgets conservative and counts total tokens, even when a provider bills cached input differently. Provider cache savings depend on the provider, model, repeated prompt prefixes, and provider reporting. Anthropic cache control is used only for eligible repeated draft work and falls back to normal generation when unsupported.
Linear tickets are not being created
Symptom: next actions are detected, but no Linear ticket is created.
Fix: in ReplyRabbit settings, check the Linear API key, the selected team, and whether tickets are sitting in a pending state waiting for confirmation. Also confirm your tier includes Linear: manual Linear ticket creation is a Pro feature, and automatic ticket creation is a Team feature.
Jira issues are not being created
Symptom: a conversation needs engineering work, but no Jira issue is created.
Fix: in ReplyRabbit settings, confirm Jira is selected as the mailbox issue tracker. Check the Jira Cloud site URL, account email, API token, default project, and default issue type. Also confirm your tier includes issue creation: manual Jira issue creation is a Pro feature, and automatic issue creation is a Team feature. For the full setup path, see Jira integration.
Workflow Tags are not being applied
Symptom: you expected tags such as rr_priority_critical, rr_no_reply_needed, or rr_linear_issue_created, but the conversation has no ReplyRabbit tags.
Fix: open the mailbox's ReplyRabbit settings and confirm Enable workflow sync and Apply FreeScout tags are on in the Workflow Tags section. If signal tags are missing, confirm AI Signals is on and the conversation has been analyzed. If Linear tags are missing, confirm the conversation has a ReplyRabbit-created Linear issue.
If FreeScout Workflows recipes are not firing, first confirm ReplyRabbit is adding the expected FreeScout tag. Then test whether your installed Workflows module reacts to programmatic tag changes. ReplyRabbit can apply the tags, but the Workflows module controls whether a recipe runs from that tag change.
Knowledge sources: a draft didn't use my help pages, Knowledge Base, products or earlier replies
Symptom: a draft ignored information you know is in your help pages, Knowledge Base, product list or earlier replies.
Fix: start with the line under the draft in the reply editor. It lists what the draft used, for example "Included: 2 help pages, 1 Knowledge Base article, 3 earlier replies to this customer". Click it to see links, plus a note for each switched-on source that added nothing:
- Switched on but nothing indexed yet: indexing hasn't finished. Check the queue worker (see below), then wait for indexing to complete.
- No good match for this message: the source is fine, but nothing in it matched this customer's message closely enough. Add or improve content that answers this kind of question.
- Index above the search limit: once the index passes 6,000 indexed sections, only keyword matching runs, not meaning-based matching. Remove sources you don't need to bring it back under the limit.
- Your plan doesn't include it: that source isn't available on your current plan.
- Knowledge Base module isn't installed or active: install or activate it under Manage > Modules.
Setup status warnings
The setup status banner in mailbox settings now warns when:
- The queue worker doesn't seem to be running. Indexing and auto-drafts never finish without it. FreeScout runs the queue through the cron job
php artisan schedule:runor aqueue:workprocess, so make sure one of them is set up. - No knowledge source is switched on. Turn on at least one in Mailbox settings, Knowledge sources.
- A source is switched on but not indexed yet. Let indexing finish.
Website sources
- The crawl stops at 200 pages by default, and the source now says so, with a button to raise the limit. Save your settings afterwards, then crawl again.
- Pages that can't be read are counted with a reason, for example blocked by the site (403), not found (404), too many requests (429), a server error, too large, or no readable text (often a page built with JavaScript). Ask your host to let the crawler through, or point the source at pages that don't need JavaScript.
- Very long pages are shortened to about 24,000 characters. When semantic matching is on, the source shows how many pages were shortened. Split long pages if the part you need is near the end.
Outline and meaning-based matching
- Outline sync stops at 1,000 documents. Documents beyond that aren't synced.
- Meaning-based (semantic) matching needs an embeddings provider. Some embedding models aren't calibrated for meaning-only matches yet and show a warning, so switch to a different embedding model if you see it.
Still stuck?