troubleshooting
121 posts.
Why installing VICIdial yourself is harder than it looks
A clean VICIdial install means compiling Perl and Asterisk, sorting codecs and NAT, tuning MySQL, and wiring the keepalive cron. The 3am failure modes are where it bites.
Read postCommon VICIdial install errors and fixes
The install errors that actually stop a VICIdial build — missing Perl modules, Asterisk compile failures, MySQL grant problems, and SELinux — and how to clear each one.
Read postHow to fix an external-phone agent whose phone never rings
An external-phone agent logs in but the phone never rings. The fix is almost always one wrong field on the phone record.
Read postHow to test a Remote Agent's External Extension before going live
Before flipping a Remote Agent to ACTIVE, dial its External Extension from the server. This one test catches most forwarding failures.
Read postHow to troubleshoot a Remote Agent that isn't getting calls
A Remote Agent set up correctly but receiving no calls usually fails one of four checks. Walk them in order to find the gap.
Read postHow to safely delete an Email Group in VICIdial
Deleting an email in-group is a two-step confirmation. Click the delete link, then click the second confirmation link that appears, so you never remove a group by accident.
Read postWhat the Email Frequency Check Rate does and why 10 minutes
The Frequency Check Rate sets how often VICIdial logs into your mailbox. Five minutes is the floor, but ten is safer, and with Gmail it is a hard requirement.
Read postWhat the Un-handled Emails count tells you
The Un-handled Emails number on an email account shows how many messages are sitting in the outside mailbox waiting to be pulled in. It is a quick health check for your inbound email.
Read postWhat the "E" keepalive and inbound email parser do
Two server-side pieces make VICIdial email actually move: an "E" keepalive on one server and the inbound email parser running every minute. Here is what each one is for.
Read postWhat the POP3 Auth Mode setting does (APOP, CRAM-MD5, PASS)
Auth Mode controls how VICIdial proves who it is to a POP3 mail server. Here is what BEST, APOP, CRAM-MD5, and PASS each mean and when to override the default.
Read postActive Account vs Status on a VICIdial phone
VICIdial phones have both an Active Account toggle and a Status field, and they do different jobs. Here is how each one affects whether the phone works.
Read postWhy Every Phone in an Alias Needs the Same Login Password
A phone alias only works if all its phones share one login password — here is why that rule exists and what breaks when you ignore it.
Read postHow a Phone Alias Keeps Agents Online When a Dialer Fails
When a VICIdial server fails, agents on a phone alias just log out and back in to land on a healthy dialer — no credential changes.
Read postWhen to use Conf Override Settings on a phone
Conf Override Settings lets one VICIdial phone carry custom Asterisk config — but only when no template is set and conf generation is on.
Read postWhy Local GMT must ignore daylight saving time
The Local GMT field on a VICIdial phone must use the standard-time offset and never adjust for daylight saving. Here is why, and what breaks if you do.
Read postWhy you can't edit a Timeclock record
The most common reasons a VICIdial Timeclock edit is blocked: the user is still clocked in, or the new times fail validation.
Read postFix the Reserved Dialplan Number warning
The VICIdial Reserved Dialplan Number warning means the number you picked cannot be dialed. Here are the reserved ranges and how to choose another.
Read postWhat the Scheduled Callbacks Display Days setting does
Scheduled Callbacks Display Days trims the agent callback list to only the callbacks set to trigger within a set number of calendar days from today.
Read postHow to cap how many callbacks an agent can hold
Scheduled Callbacks Active Limit caps how many active or live user-only callbacks an agent can hold, blocking the My Callback checkbox once the cap is hit.
Read postWhat the Anyone Callbacks DNC Filter setting does
Anyone Callbacks DNC Filter checks ANYONE callback phone numbers against the campaign's enabled DNC options before they enter the hopper to be dialed.
Read postWhy your scheduled callbacks aren't firing
Callbacks that never come due usually trace to one of five causes: a missing agent user option, callbacks off at the campaign, a future trigger time, anyone-callbacks not in the hopper, or a calltime block.
Read postHow to trace one bad call end to end across the log reports
Follow a single problem call through the Dial Log, Hangup Cause, Carrier, Caller ID, and AMD reports in order to find the real cause.
Read postDiagnosing LAGGED spikes by server with the summary chart
Use the Agent LAGGED Report and the LAGGED Summary chart to spot lag clusters on a timeline, tie them to one server, then check latency.
Read postWhat to check yourself before opening a VICIdial support ticket
A calm self-check list: clock, agent screen, carrier registration, hopper, dispositions, and which log report matches your symptom.
Read postDiagnosing choppy or robotic audio on agent calls
Choppy, robotic, or garbled call audio almost always comes from the RTP path: jitter, packet loss, a codec mismatch, or a CPU-starved dialer.
Read postDiagnosing a 3-way transfer that won't connect using the press log
When a 3-way transfer never reaches the outside party, the 3-Way Press Log Report shows exactly which step failed using its Results events.
Read postDiagnosing agent session problems with the Latency Gaps Report
A latency gap is a missing stretch of agent latency log entries while an agent was supposed to be logged in, and those gaps often explain agent-screen session trouble.
Read postWhen an agent can't hear the customer but the customer hears them
One-way audio means RTP is flowing in only one direction, almost always blocked by NAT, a firewall, or routing on the agent's leg.
Read postWhen AMD marks live people as answering machines: how to diagnose it
Answering Machine Detection that flags live customers as machines drops real prospects. Here is how to read the AMD Log and tune sensitivity.
Read postWhy some form fields reject spaces, dashes, and special characters
VICIdial strips many special characters from form fields on purpose, because certain character combinations can corrupt or delete data in the system.
Read postDiagnosing API integration failures with the API Log Report
When a CRM integration stops pushing leads or updating dispositions, the API Log Report filters by user, function, and result so you can see exactly what failed.
Read postWhen recordings exist but have no sound: what to check
A recording file that exists but plays silent points at the RTP and mux path: codec, recording format, and the recording delay rather than missing files.
Read postWhat HUC statuses (enhanced disconnect logging) tell you about failed calls
An HUCXXX status is an enhanced disconnect-logging level 3 record, where XXX is the carrier disconnect code that ended the call.
Read postWhy two agents end up in the same session talking to each other
Two agents hearing each other instead of customers almost always means a previous agent never logged out cleanly and left the session open.
Read postDiagnosing intermittent agent disconnects across a shift
Random agent disconnects that you can't reproduce are best traced with the Agent LAGGED, Agent Latency, and Latency Gaps reports read together.
Read postDatabase and Asterisk reload issues: a safe order of operations
Restarting the database or Asterisk under load drops calls. Here is the safe order: make the admin change, let the keepalive apply it, then reload only if needed.
Read postWhen live monitoring connects but you can't hear the call
Monitoring shows connected but the manager hears nothing. The Real-Time Monitoring Log confirms the session happened; no audio almost always means phone, conf, or codec.
Read postWhat the PDROP status means and why it points at carrier behaviour
PDROP is a pre-routing dropped call, hung up the instant the Answer signal arrives, which is the fingerprint of a carrier false answer.
Read postDiagnosing calls that drop while the customer is on hold
Customers vanishing while parked on hold is measurable. The Agent Parked Call Report shows holds per agent, average hold time, and how many dropped while parked.
Read postHow to check the SIP registry on the Asterisk Debug Page
The Asterisk Debug Page shows SIP Peers and Registry from the dialer itself, so you can confirm whether a phone or trunk is actually registered.
Read postDiagnosing slow reports and why they can stall the whole system
Slow reports do more than test your patience — they can stall the whole dialer. The Admin Report Log Viewer shows each report's run time so you can find the offender.
Read postWhy calls ring but never connect to an agent
Calls that ring out, drop, or sit unanswered usually trace back to the hopper, agent availability, or a carrier that never sends a real answer.
Read postWhy agent screen buttons stop responding mid-shift
When agent screen buttons go dead mid-shift, the Agent Debug Log Report shows the clicks and AJAX calls so you can tell network from workstation from database.
Read postWhy so many calls land on NA (no answer) and what it really means
NA is No Answer AutoDial, a catch-all for any outbound call that never gets an Answer signal, from ring-no-answer to congestion to plain errors.
Read postDiagnosing recording-access questions with the Recording Access Log
When someone asks who listened to a recording, the Recording Access Log answers it — search by access date, recording date, or the user who did the listening.
Read postVICIdial time-sync issues: how clock drift breaks call times and stats
When a VICIdial server clock drifts out of sync, call-time windows, callbacks, and report timestamps all skew. Here is how to spot it and fix it with NTP.
Read postWhen to reload Asterisk and when it makes things worse
Reloading Asterisk re-reads its config but can interrupt live calls. Here is when a reload actually helps, when VICIdial handles it for you, and when to wait.
Read postWhen the Dispo Call URL doesn't fire: finding it in the URL Log
The Dispo Call URL is meant to fire on disposition, and the URL Log Report records each request so you can prove whether it actually went out.
Read postWhen the WEBFORM button does nothing: tracing it in the URL Log
The WEBFORM button click is recorded in the URL Log Report, so you can prove whether the request fired and where the broken link really is.
Read postDiagnosing high agent latency: the reports that point to the cause
Use the Agent Latency Report and Latency Gaps Report to tell whether agent-screen lag is the network, the workstation, or the server.
Read postHopper empty errors: what they mean and how to clear them
An empty dial hopper means no leads queued for agents. Check list status, call times, recycling and time zone to refill it.
Read postHow to read the 3-Way Press Log Report and what each result means
Decode every row of the 3-Way Press Log Report, from Started to Transfer, and tell a clean handoff from a failed one at a glance.
Read postRecordings missing in VICIdial: where they go and how to find them
A recording you expected is not there. Where VICIdial recordings actually live, why one might never exist, and how to confirm it.
Read postHow to read the Inbound DID Detail Report to trace a single inbound call
Use the Inbound DID Detail Report to follow one inbound call by DID and tell where it actually routed versus where the number points today.
Read postWhat CONGESTION means in VICIdial and how to stop it
CONGESTION means the carrier couldn't place the calls you sent. It's a capacity or route problem on their side, or you over-dialed. Here's how to confirm and back off.
Read postDiagnosing false answer supervision with the SIP Event Report
The SIP Event Report lets you sort SIP messages by Ring-Time to spot False Answer Supervision — calls marked answered before a human picked up.
Read postDiagnosing carrier rejects: reading the codes your provider sends back
Use the Hangup Cause and Carrier Log reports to read your carrier's rejection codes, filter to a specific cause, and decide what to change.
Read postWhen the webphone won't register: a step-by-step checklist
The browser webphone fails to register over WebSocket. Work through WSS URL, cert, SIP secret, ports and mic permission in order.
Read postWhy agents get logged out with a LAGGED message and how to fix it
A LAGGED message means the agent screen's heartbeat to the dialer fell behind. Here's how to confirm it in the LAGGED reports and what to change.
Read postWhy agents can't log in to a campaign before 9 AM
No leads in the hopper means no agent logins. With a 9am-9pm call time, leads aren't loaded until 9 AM in the first lead time zone.
Read postHow to read the Webserver-URL Report on a multi-server setup
The Webserver-URL Report bundles three logs that show which web server an agent hit and which page version they got on a cluster.
Read postWhat CHANUNAVAILABLE means and why it's usually a line-count problem
CHANUNAVAILABLE means the dialer ran out of lines before it could hand the call to the carrier. It's a local capacity limit, not a carrier reject.
Read postWhy your drop rate suddenly spiked and how to trace it
A sudden drop-rate jump usually traces to dial ratio, fresh leads, fewer agents, or false answer supervision. Here is how to find which.
Read postAgent screen frozen or stuck loading: what to check first
A frozen VICIdial agent screen is almost always the agent's network or workstation. Here's the order to check, and which reports prove it.
Read postWhat hangup cause 21 (call rejected) means and who's rejecting it
Cause 21 means something actively refused your call. Usually it's caller-ID reputation. Here's who rejects and what to change.
Read postCalls placed but not connecting: a first-things-to-check guide
Calls dial out but never reach a person? Read the per-attempt SIP response codes in the Dial Log and Carrier Log reports to find the cause.
Read postWhat SIP Cause 18 (request timeout) means on your VICIdial calls
Cause 18 means the far end never answered in time. Here is what it tells you about your list and carrier, and what to check first.
Read postHow to read the Recording Access Log to see who opened a recording
The Recording Access Log is your audit trail for call recordings. Here is how to search it by user, access time, or recording date.
Read postOne-way audio on VICIdial calls and how to find the cause
When one side hears and the other doesn't, RTP is flowing one direction only. Here is how to isolate the silent leg.
Read postHow to read the Admin Report Log Viewer and spot slow-running reports
The Admin Report Log Viewer lists every report pulled, with compile time. Here is how to find the slow report that is dragging your system.
Read postHow to read SIP hangup causes and translate them into plain English
The Dial Log Report groups calls by SIP hangup cause code and reason. Here is what the common codes really mean for your list and carrier.
Read postNo audio on VICIdial calls: first things to check
Total silence on both legs almost always means RTP media isn't flowing. Here is the ordered checklist to find where it stops.
Read postHow to read the User Group Login Report to confirm where an agent logged in
Use the User Group Login Report to confirm an agent's most recent login: campaign, server IP, computer IP, extension, and phone login.
Read postWhat hangup cause 17 (user busy) tells you about your list
Cause 17 is a real busy signal, logged as the AB status. A high rate is usually a list-quality or redial-timing problem, not a system fault.
Read postHow to read the Dial Log Report and what the SIP codes mean
The Dial Log Report groups every placed call by its SIP response code. Here is how to read each column and turn a wall of codes into a real diagnosis.
Read postHow to read the AMD Log Report when answering-machine detection looks wrong
The AMD Log Report shows the result of answering-machine detection on each placed call. Here is how to read it and tell real misfires from carrier noise.
Read postHow to read the Latency Gaps Report and what a gap actually means
A latency gap is a missing stretch of latency log entries while an agent was supposed to be logged in. Here's how the Latency Gaps Report reveals session trouble.
Read postHow to read the Agent-Manager Chat Log when you need a record of a conversation
The Agent-Manager Chat Log lets you view and search internal chats between managers and agents, and between agents, when you need a written record.
Read postHow to read the Agent Debug Log Report to trace one agent's session
The Agent Debug Log Report records nearly every button click and back-end call for one agent session, so you can replay exactly what their screen did.
Read postHow to read the Agent LAGGED Report to find which dialer is struggling
The Agent LAGGED Report pins lag to a specific dialer and lists every lagged event by user, campaign, and time. Here's how to read both halves.
Read postHow to read the SIP Event Report and spot false answers
The SIP Event Report sorts SIP messages by ring-time and other criteria. Here is how to enable it and use it to catch false answer supervision.
Read postHow to read the Agent Parked Call Report to see hold-time drops
The Agent Parked Call Report shows parked calls by agent and timeframe for one day, the average time on hold, and how many callers dropped while waiting.
Read postHow to read the Agent Latency Report when the agent screen feels slow
The Agent Latency Report charts the web-connection latency of logged-in agents over a day. Here's how to read it when the screen feels sluggish.
Read postHow to read the API Log Report when an integration stops working
The API Log Report shows API entries for a date and time range, filterable by API User, Agent User, Function, and Result, so you can find why an integration broke.
Read postThe VICIdial troubleshooting playbook: where to start when something breaks
A symptom-first guide that routes you from what's broken — dead dials, false answers, slow agent screens, drops on hold — to the exact VICIdial report that holds the answer.
Read postHow to read the LAGGED Summary Report and spot lag clusters over time
The LAGGED Summary Report charts agent lag events on a timeline so you can see clusters instead of single stutters. Here's how to read the pattern.
Read postHow to read the Caller ID Log Report to see which CIDs you've burned
The Caller ID Log Report breaks calls down by the caller IDs a campaign used, so you can see which numbers are burned and rotate them before they go spammy.
Read postHow to read the URL Log Report to debug webhook and webform calls
The URL Log Report records every URL VICIdial requested — dispo call URLs and WEBFORM clicks. Here's how to read it to find why a webhook or webform failed.
Read postHow to read the Hangup Cause Report and find why calls drop
The Hangup Cause Report shows the carrier hangup causes for all outbound calls. Here is how to filter it to specific causes and find why calls drop.
Read postHow to read the Carrier Log Report when calls aren't going out
When calls won't connect, the Carrier Log Report shows every dial attempt and the response code the carrier returned. Here is how to read and download it.
Read postHow to use the Asterisk Debug Page to check SIP peers and registry
The Asterisk Debug Page surfaces live SIP peers, registry status, and the last 1000 CLI lines so you can confirm a trunk is registered without SSH.
Read postHow to read the Real-Time Monitoring Log Report to see who listened in
The Real-Time Monitoring Log Report shows which manager monitored which agent, when, for how long, and what kind of session it was.
Read postWhy a recording plays back silent and how to fix it
Silent VICIdial recordings usually mean no audio path reached MixMonitor, DTMF muting stayed on too long, or stereo channels were misconfigured. Here is how to trace and fix each scenario.
Read postWhy recordings go missing and how to fix it
Missing recordings in VICIdial usually trace to MixMonitor not being triggered, files purged from disk, wrong recording stage, or a full filesystem. Here is how to diagnose each cause.
Read postWhy the agent recording button does nothing and how to fix it
If the VICIdial agent recording button does nothing, the most likely cause is Campaign Recording set to NEVER. Here is how to diagnose and fix it.
Read postFix: "agent_user does not have a live call" on a transfer
This transfer error means the system does not see a live call on the agent it was told to act on. Here is what causes the mismatch and how to clear it.
Read postFix: "no fronter found" when forcing a fronter leave-3-way
The no fronter found error means the force function could not match a second agent session to the call. Here is what triggers it and how to clear it.
Read postFix: "agent_user has previous active 3-way calls" when starting a 3-way
This error is a safety check firing on leftover 3-way calls. Here is what tw_check does, why it blocks you, and how to clear the stale conference.
Read postWhy you hear no ringback on a 3-way call, and the Dial Prefix fix
When an agent starts a 3-way call and hears dead air instead of ringing, the 3-Way Call Dial Prefix is usually the setting to change.
Read postFix: "ingroup is not valid" when transferring to a closer queue
The ingroup is not valid error means the in-group you passed to a transfer is not a single active queue. Here is how to find and fix the bad value.
Read postAMD isn't working: the checklist to run through
AMD passing every call straight to agents or dropping live people? Work this checklist of dialplan, reload, and campaign settings to find the break.
Read postCodec mismatch with your carrier: how to fix it
A codec mismatch shows up as no audio or a 488 rejection. Pin the same codec on both ends and the call connects cleanly.
Read postCarrier won't register: what to check
When a VICIdial carrier won't register, walk a short checklist: registration string typos, wrong host or port, NAT, credentials, and the firewall on 5060.
Read postOutbound calls failing at the carrier: first checks
When outbound calls fail at the carrier, run the first checks: trunk active, peer reachable, dial pattern correct, caller ID valid, and any 503 or 603 response.
Read postList Change Date and List Last Call Date Explained
Two timestamps on every VICIdial list quietly tell you when settings last changed and when a lead last dialed. Here is how to read them and why they matter.
Read postLeads Dialing in the Wrong Time Zone: How to Fix It in VICIdial
Calls going out too early or too late usually mean leads coded to the wrong time zone. Here is how it happens and how to fix it.
Read postWhy a VICIdial List Shows 0 Leads Available
The list has thousands of records but the dialer reports zero available. Here is what 'available' actually means and how to fix it.
Read postLeads Not Dialing? List-Level Causes in VICIdial
When a list of leads sits there and nothing dials, the cause is usually a setting on the list itself. Here is the checklist.
Read postDID isn't routing calls: first things to check
When a VICIdial DID receives a call but sends it nowhere useful, start with these settings.
Read postCallers stuck on hold forever: common causes
Why VICIdial callers can sit on hold even when agents are free, and the in-group settings behind it.
Read postInbound calls not reaching agents: what to check
A short checklist for when VICIdial inbound calls arrive but never get handed to a logged-in agent.
Read postBuilding a 3-tier overflow ladder for a full queue
What happens when nobody is logged in, the queue is jammed, or it's after hours? VICIdial gives you separate fallbacks for each. Here's how to stack them into a clean overflow ladder so no call falls off a cliff.
Read postOn Hold Prompts: messages while callers wait
An on-hold prompt plays a short recurring message to waiting callers, but it blocks them from reaching an agent while it plays. Here are the rules that keep it from quietly inflating your hold times.
Read postAgent Search Method Override for in-groups
This in-group setting decides whether VICIdial looks for an answering agent across all your servers or just the one where the call landed. The wrong choice can quietly raise your dropped calls.
Read postDial Timeout too short: the symptoms
If your campaign hangs up on people before they pick up, the Dial Timeout is probably set too low. Here is how to spot it and where to land the number.
Read postIs it your dial level or your list quality?
When numbers look off, operators blame either the dialer settings or the leads. Usually it is the interaction between the two. Here is how to tell which one is actually your problem.
Read postToo many dropped calls: the common causes
Your drop rate is creeping up and you are not sure why. Here are the usual suspects in VICIdial, from a dial level set too high to a list that just answers too well.
Read postAgents idle but no calls coming: dialing-strategy causes
The campaign is active and the hopper has leads, yet agents sit waiting. This is usually the dialing math, not a broken dialer. Here are the strategy settings that quietly throttle calls to a trickle.
Read postWhy VICIdial isn't dialing: the first things to check
Agents logged in, phones quiet, and no idea why. Before you panic, VICIdial almost always stops dialing for one of a short list of plain reasons. Here is the checklist to run, top to bottom.
Read postWhen to force a reset of the hopper
Force Reset of Hopper wipes the dialing queue clean on form submit, then lets it refill a minute later. It's a handy reset button for stuck or stale queues — and a fine way to dial the wrong leads if you use it carelessly. Here's the safe way.
Read postHow to fix an empty hopper in VICIdial
Agents logged in, leads in your lists, but the hopper keeps showing empty and nothing dials. Work through these usual causes in order to get calls flowing again.
Read post