Troubleshooting
The fastest fixes for common issues. If your problem isn’t here, check the in-app Settings → Audit log and Settings → System logs — most issues leave a clear trace.
Login issues
”We couldn’t find your account”
| Cause | Fix |
|---|---|
| You signed in with a different identity provider than usual | Try Google/Microsoft/email — whichever you used originally. |
| SSO required and you’re on a non-SSO email | Use your work email through SSO. |
| SCIM hasn’t created you yet | Have your admin trigger a sync, or use JIT provisioning. |
| Account deactivated | Ask your workspace admin to restore. |
Loop redirect during SSO
Almost always a clock-skew issue. Check that your IdP’s clock and Omniflow’s are within 5 minutes. Restart any container with stale time.
MFA not prompting
If your IdP enforces MFA, the prompt happens at the IdP, not Omniflow. If you’re not seeing it, your IdP’s MFA policy isn’t applied to the Omniflow app.
Voice / call quality
Customer hears silence at start
The agent waits ~1.5 seconds before speaking by design (so the customer’s “hello” doesn’t get cut off). If silence is longer, check:
- The agent has a welcome message configured.
- Voice provider isn’t returning an error — check the agent’s activity log.
- Consent prompt isn’t muted (regional setting).
Customer hears agent twice
Echo cancellation is misconfigured on the telephony bridge. For Twilio, ensure Media Streams track="inbound_track" not "both_tracks". For Genesys, check the SIP trunk’s echo cancellation settings.
Lag mid-call
| Cause | Fix |
|---|---|
| Slow tool call | Inspect tool latency in the trace. |
| Failover triggered | Check Reliability dashboard; primary may be degraded. |
| Long retrieval | Tune retrieval depth on the agent’s knowledge config. |
One-way audio
Almost always firewall: SIP/Media Streams need bidirectional UDP/RTP or WebSocket connectivity. Check your network rules.
Agent quality
Agent gives wrong answer
Open the trace. Check:
- Was the right knowledge chunk in the retrieval results?
- Did the agent call the right tool?
- Is the prompt clear about the policy?
If retrieval missed the right chunk, the article needs better text or different chunking.
Agent hallucinates
Tighten the prompt with “If you don’t know the answer, say so and offer to escalate.” For voice agents, keep the prompt under ~150 tokens — long prompts hurt voice fidelity.
Agent ignores tools
The tool’s name and description matter. Rename ambiguous tools, sharpen descriptions. Test with a deliberately easy question to confirm the tool is registered.
Integrations
CRM sync silently failing
Check the integration’s audit log under Settings → Integrations → [CRM] → Audit. Common causes:
- OAuth token expired (rare, but happens after policy changes).
- Field-level security blocking the integration user.
- Custom fields in CRM that don’t exist in Omniflow.
Email sending failing
| Symptom | Fix |
|---|---|
| All sends bouncing | Check Gmail/Outlook integration health. Re-auth the connector. |
| Specific addresses bouncing | The recipient’s mailbox is rejecting. Check the bounce reason in the audit log. |
| Sends going to spam | Check SPF, DKIM, DMARC alignment. Use a tool like mail-tester.com. |
Genesys recordings not syncing
The integration user needs recording:readonly. Recordings finalize 1-3 minutes after the call ends; sync runs every 5 minutes. If still missing after 30 minutes, force-resync from the integration page.
QA Analytics
Scores not appearing
Conversations are scored asynchronously. Allow ~30 seconds. If still missing:
- Check the scorecard’s
statusfield;failedmeans the grader hit an error. - Check the system_logs for
qa-gradererrors. - Re-import the conversation if the transcript was malformed.
AI score wildly different from coach review
This is what calibration is for. Sample 30 calls, score blind, compare. Refine the rubric description until they converge. See Scoring Rubric.
API
401 Unauthorized
| Cause | Fix |
|---|---|
Missing Authorization header | Add Authorization: Bearer omf_live_... |
| Wrong API key prefix | omf_live_ for live, omf_test_ for test. |
| Key revoked | Generate a new key. |
403 Forbidden
The key lacks the required scope. Check the key’s scopes under Settings → API Keys. Add the missing scope or use a key that has it.
429 Too Many Requests
Hit the rate limit. Back off using Retry-After. For sustained high volume, request a higher rate limit on the key.
409 Conflict on create
Duplicate external_id. Add upsert: true to the request body, or omit the external_id if you want a new resource.
Webhooks
Endpoint never receives events
| Check |
|---|
| Endpoint URL reachable from the public internet? |
| Returns 2xx within 8s? |
| Subscription enabled? |
| Events match what’s firing? |
The Webhook deliveries log shows attempts and responses. Filter by failed to see what’s bouncing.
Signature verification fails
| Cause | Fix |
|---|---|
| Wrong secret | Re-copy from the subscription. |
| Body parsed before verification | Verify against the raw bytes, not the parsed JSON. |
| Clock skew | Reject if X-Omniflow-Timestamp is more than 5 minutes off — but check your server’s clock too. |
When to escalate
If something’s broken at the platform level (sustained 5xx, voice runtime down, integration provider outage), check the public status page first. If it’s degraded, your incident is upstream of your config — wait or fail over.
For account-level issues that aren’t covered here, contact support from inside the app — the support thread auto-attaches the recent audit log so the team has context.
Most “broken” reports turn out to be config issues, not bugs. Reading the audit log first usually finds the answer in seconds.
Open in Omniflow
Related
| If you want to… | Go to |
|---|---|
| Read the runtime architecture | Voice Runtime |
| Understand the API | API Reference |
| Get help inside the app | Settings overview |