When something isn't working, this is the page to check first. Symptoms are listed by where you'd notice them — start with the section that matches what you're seeing.
First, don't panic. Most issues are configuration, not bugs. The platform is designed so you can't break anything important — pause the deployment, fix the issue, resume. Even an ugly issue rarely costs you more than the cost of a few wasted test calls.
If you can't find your issue here: Email support@hirefinn.ai with the deployment ID, the call ID (if applicable), and a description of what you expected vs. what happened. Include screenshots if visual.
Test calls
"My test call never came through."
| Likely cause | What to check |
|---|
| Phone number format wrong | Include country code. US: +15551234567. India: +919876543210. The platform shows a "tested format: …" preview before triggering. |
| Trial credit exhausted | Settings → Plan and billing → Usage. New accounts get $25 credit. |
| Number on global suppression list | Settings → Compliance → Do Not Call List → search for your number. |
| Carrier rejection | Some carriers (especially international) block calls from new numbers. Try a different from-number. |
| Spam blocker on your phone | Apple/Google spam filters sometimes silently block. Try from a different from-number. |
"Test call came through but the Finn was silent / weird."
| Likely cause | What to check |
|---|
| Welcome message set to defined but field is empty | Edit Finn → Welcome Message → ensure there's text in the field or switch to dynamic |
| Voice not properly assigned | Edit Finn → Voice → re-select. Some voices require a region match. |
| LLM service misconfigured (advanced) | Edit Finn → AI Service Configuration → reset to default |
| Microphone permission issue on Finn side | Refresh, try again. Persistent: contact support. |
Building / editing a Finn
| Likely cause | What to check |
|---|
| Required field empty | Look for red labels — usually Name, Voice, or Language. |
| Validation error in workflow | If using Workflow tab, check for nodes with red borders. |
| Browser session expired | Refresh, log back in, try again. Your edits autosave drafts. |
"My Finn isn't following the script I wrote."
| Likely cause | What to fix |
|---|
| Identity field too vague | Be specific. "You are Maya, a friendly receptionist" beats "You are an AI assistant." |
| Guardrails buried under too many other instructions | Move critical guardrails to their own dedicated field (Style & Guardrails). |
| Conflicting instructions across fields | Audit Identity + Style + Welcome + Workflow for contradictions. |
| Knowledge base contains contradictory info | Open the Knowledge tab in Data Extractor Sidebar for a sample call to see what was retrieved. Remove contradictions from KB. |
| Free-form when you need structure | If you have a strict required-order flow, use Workflows instead. |
"The Finn is too chatty / not chatty enough."
| Symptom | Fix |
|---|
| Too talky | Add to Response Guidelines: "Keep responses under two sentences unless asked for more detail." |
| Too brief | Add to Response Guidelines: "Give complete answers with examples when relevant." |
| Interrupting the caller | Tune Settings → Call Settings → Interruption Sensitivity (lower = more patient) |
| Long awkward silences | Tune max_idle_duration lower (e.g. 5s instead of 10s) |
"My Finn keeps asking the same question twice."
| Likely cause | Fix |
|---|
| The caller's answer didn't match the expected format | Soften the Ask node's parser, or rephrase the question |
| LLM didn't capture the answer to memory | Add to Response Guidelines: "Once a question is answered, do not ask it again." |
| Workflow loop bug | Open the workflow → check for an edge that loops back to the Ask node |
Knowledge Base
"Finn isn't answering questions I know are in the documents."
| Likely cause | What to check |
|---|
| Documents not indexed yet | Knowledge Base tab → check status. Should say Indexed. Click Re-index Now if stuck. |
| Document is image-only PDF | Scanned PDFs aren't OCR'd. Convert to text first (e.g. with Adobe or an online OCR tool). |
| Document too long, retrieval misses relevant section | Split the document into smaller focused files. |
| Question phrasing doesn't match document phrasing | Open Data Extractor Sidebar → Knowledge tab for a sample call → see what was retrieved. If wrong snippets came back, KB needs more semantic coverage. |
| File over 25 MB size limit | Compress or split. |
"Finn is giving outdated answers."
| Likely cause | Fix |
|---|
| Old version of document still in KB | Knowledge Base → delete old file, upload new one |
| Website import has stale cached content | Knowledge Base → Website Imports → [URL] → Re-crawl Now |
| Cached query result (rare) | Click Re-index Now to force refresh |
Deployments
"I clicked Launch but no calls are going out."
| Likely cause | What to check |
|---|
| Outside calling-hour window | Deployments only dial during the configured calling-hour window in caller's local time. If you launch at 8 AM PT with 9-6 calling hours, first call won't go out until 9 AM. |
| Audience empty | Open the audience and confirm it has rows. Sync issues can leave it empty. |
| All numbers suppressed | Settings → Compliance → Do Not Call List. If you accidentally suppressed your test list, remove them. |
| From-number not registered | US numbers without caller ID registration fail silently. Check Settings → Phone numbers → [Number] → Registration Status. |
| Spend cap hit | Live Deployments → health panel will show "Cap reached." Raise cap or wait for next period. |
| Deployment paused | Live Deployments → click deployment → check status. |
| Likely cause | Fix |
|---|
| Caller ID showing "SPAM LIKELY" | Register caller ID. Without registration, US carriers label your calls as spam and answer rates collapse. |
| Welcome message sounds like spam | Tighten the opening. "Hi, this is [name] calling from [recognizable company name] about [reason they'd expect a call]." The "about" matters — generic openings get hung up on. |
| Calling at bad hours | Verify calling-hour window is being applied. |
| List is cold (no prior relationship) | This isn't a Finn problem — it's a list problem. Cold lists always have low pickup-and-stay rates. |
"Deployment is paused but I don't know why."
Live Deployments → click deployment → scroll to Pause Reason. Common reasons:
| Reason | What it means |
|---|
| Spend cap reached | Configured per-deployment cap was hit. Raise it or close the deployment. |
| Audience exhausted | All contacts called (with retries). Either complete the deployment or add more contacts. |
| Buffer drained | Dispatcher ran out of work momentarily. Usually self-recovers within a minute. |
| Manual pause | You or a teammate hit Pause. Check the audit log. |
| Carrier outage | Telephony provider issue. Resumes when their outage ends. |
| Plan limit hit | You've used your plan's monthly call allotment. Upgrade or wait for next cycle. |
Analytics
"Analytics shows zero calls but I know calls happened."
| Likely cause | Fix |
|---|
| Looking at wrong deployment | Check the deployment dropdown — easy to land on a different one |
| Cache stale | Click Refresh (button shows up when "Cached" badge is visible) |
| Calls were under 5 seconds | Some metrics filter out very-short calls (treated as no-answer). Look at the full call log. |
"Post-call analysis fields are blank."
| Likely cause | Fix |
|---|
| Fields added after the deployment started | Post-call analysis only runs on calls that completed after the field was added. New calls will be populated. |
| Field question is too vague | Reword. "Did the caller express interest?" is better than "Interest level?" |
| Transcript is too short | If a call lasted 5 seconds, there's nothing to extract from. |
| LLM extraction error | Rare. Check the call's Extraction Status in the sidebar. |
"Sentiment seems wrong on calls."
Sentiment analysis isn't perfect. It's a useful indicator, not a verdict. If consistently misclassifying, add a custom post-call field with a more specific question (e.g. "Did the caller seem satisfied with the resolution?") and use that instead.
Phone numbers
"I bought a number but can't use it."
| Likely cause | What to check |
|---|
| Compliance verification pending | Some countries (India, France, Germany) require KYC. Settings → Phone numbers → [Number] → Compliance Status. |
| Caller ID not registered (US) | Outbound calls fail with "carrier rejected" until registered. |
| SIP trunk misconfigured (BYO) | Settings → Telephony Account → test trunk. Common: codec mismatch, wrong credentials. |
| Number not assigned to a Finn (inbound) | Settings → Phone numbers → [Number] → Default Inbound Finn → assign one. |
"Outbound calls fail with 'carrier rejected.'"
| Cause | Fix |
|---|
| Caller ID not registered (US/Canada) | Settings → Phone numbers → [Number] → Caller ID Registration |
| Destination country requires sender verification | KYC under Settings → Phone numbers → Compliance |
| From-number capability doesn't include voice | Buy a voice-capable number; SMS-only numbers can't make calls |
| Carrier is filtering known-bad senders | Try a different from-number; old numbers sometimes get blacklisted by carriers |
Integrations
| Likely cause | Fix |
|---|
| Sync schedule too infrequent | Settings → Integrations → [CRM] → set to every 15 min or hourly |
| CRM token expired | Re-authorize the integration |
| Filter excludes new contacts | Open the audience's CRM filter and verify the criteria |
| CRM API rate-limited | Wait and retry. Heavy syncs can trigger CRM-side limits. |
"My webhook isn't receiving events."
| Likely cause | What to check |
|---|
| URL unreachable from internet | Use a public URL, not localhost. For local testing, use a tunnel (ngrok, Cloudflare Tunnel). |
| Returning non-2xx response | The platform expects 200-299. 3xx/4xx/5xx triggers retry. |
| Endpoint timing out | Must respond within 10s. For long-running logic, accept the webhook quickly and process asynchronously. |
| HMAC signature mismatch | Verify your signing implementation matches our spec — see Integrations → Webhooks. |
"Calendar bookings aren't appearing in my calendar."
| Likely cause | Fix |
|---|
| Wrong calendar selected | Settings → Integrations → Calendar → check selected calendar |
| Permissions revoked in calendar provider | Re-authorize the integration |
| Booking went to a calendar you don't view | Many people have multiple calendars; the booking is somewhere. Check "all calendars" view. |
| Calendar event title misleading | Bookings default to "Appointment via FinnAI" — search by that |
Billing
"My invoice is higher than expected."
Settings → Plan and billing → Usage → Anomaly Flags. Look for line items >2x your trailing 30-day average. Common causes:
- A Finn ran on a hostile audience and got into long stuck calls (set
limit_call_duration).
- A deployment was launched without a spend cap and dialed a much bigger list than intended.
- Premium voice or premium model was enabled (Settings → Plan).
- A new country was added — international telephony rates can be 10-50x US rates.
"I want a refund for a wasted deployment."
Email billing@hirefinn.ai with the deployment ID and an explanation. Bug-related issues are typically refunded. User-configuration mistakes typically aren't, but reach out anyway — case-by-case.
Account & access
"I can't log in."
| Likely cause | What to try |
|---|
| Forgot password | Click "Forgot password" on the login page |
| Account locked after too many failed attempts | Wait 15 minutes, then try again |
| Email not confirmed | Check spam folder for confirmation email |
| Team account but you weren't invited | Ask your admin to invite you via Settings → Team |
| SSO not working | If your org uses SSO, you must log in via the SSO link, not email/password |
"I lost access to my account / lost 2FA device."
Email support@hirefinn.ai with proof of account ownership (billing email, last 4 of payment method, etc). We'll help you recover access.
"Latency is too high — Finn takes too long to respond."
Target: <800ms between end-of-user-speech and start-of-Finn-response.
| Cause | Fix |
|---|
| Premium voice selected | Switch to a standard voice (-100-200ms) |
| Far-away region | Set account region during signup to closest to your callers |
| Network issues at carrier | Usually transient — wait a few minutes |
| Complex workflow with deep nesting | Simplify; collapse sub-flows |
| Large knowledge base + slow retrieval | Settings → Knowledge → re-index, or reduce KB size |
"Finn sounds robotic / not human enough."
| Cause | Fix |
|---|
| Standard voice tier | Try a premium voice |
| Language mismatch | Confirm voice's primary language matches what you're speaking |
| Response Guidelines too restrictive | "Keep responses under one sentence" makes it feel terse. Loosen. |
| Workflow forcing rigid script | Switch to free-form, or use Say nodes more sparingly |
When all else fails
- Pause the deployment — stops dialing, no more cost incurred.
- Look at a recent failed call — open the Data Extractor Sidebar for full context.
- Search this troubleshooting page with Ctrl+F for keywords from your error.
- Email support — support@hirefinn.ai with deployment ID, call ID, and your description.
- Use the chat-bubble Finn — bottom-right corner — it's trained on these docs and can usually resolve issues instantly.
- For Enterprise customers — your dedicated CSM is in your Slack channel.
Next
- FAQ → — questions that aren't quite troubleshooting.
- Compliance → — things that fail because of legal/regulatory issues.
- Glossary → — definitions for any term you don't recognize.