VICIdial Troubleshooting: Symptom-First Guide

VICIdial troubleshooting works fastest symptom-first: match what the floor is seeing — dropped calls, dead air on connect, one-way audio, an empty hopper, spam labels — to the layer that owns it (dialer configuration, the Asterisk server, or the carrier), then apply that layer’s fix. Most chronic dialer symptoms trace to one dominant cause, and this guide routes each symptom to its fix.

You searched a symptom, not a cause — that’s the right instinct. Find your symptom in the table below, read which layer usually owns it, and follow the link that owns the repair.

The symptom table: what breaks, which layer owns it

Symptom	Usual layer	Dominant cause	Where the fix lives
Hopper empty / leads not dialing	Dialer config	Hopper gates: cron, campaign/list state, statuses, call-time windows	This page, below
Dead air when a contact answers	Dialer config	AMD analysis time — or a real audio-path fault	This page, below
Calls dropping mid-call	Server or carrier	Carrier disconnect vs. signaling/media timeout	This page, below
One-way audio	Server/network	NAT advertising a private address in SDP	One-way audio fix guide
DTMF or codec faults after setup	Dialer config	Trunk settings drift	Trunk setup guide
403 rejections in the logs	Carrier/account	Auth, CID, balance, or destination limits	SIP 403 Forbidden guide
503 bursts in the logs	Carrier	No route found or CPS limit reached	SIP 503 guide
Slow ring start after dialing	Carrier/route	Post-dial delay on the terminating path	PDD guide
Calls labeled “Scam Likely”	Network analytics	Per-carrier CID reputation scoring	Spam label fix + attestation setup
Contact rate sliding week over week	Network analytics	Reputation decay across your CID pool	Caller-ID reputation guide

Three of those symptom families are worth solving right here, because the fix is diagnosis more than configuration.

Hopper empty: leads exist, VICIdial isn’t dialing

The hopper is loaded by a script, AST_VDhopper.pl, that must run from cron every minute. If that cron entry stalls, no leads load no matter what the campaign screen says — so a silent floor starts with a cron check, not a campaign check.

When cron is fine, the script itself is a series of gates, and every gate can zero your hopper. From the script’s own logic: it only processes campaigns set active, and only pulls from lists that are attached to the campaign and active themselves. Only leads whose status appears in the campaign’s dial statuses list qualify. A lead filter, if set, excludes everything it doesn’t match.

The gate operators forget is local call time. The hopper enforces each lead’s calling window using the lead’s GMT offset against the campaign’s call-time rules — including per-state call times — so leads outside their local window are never loaded at all. A list full of West Coast numbers at 8 a.m. Eastern produces an empty hopper that fixes itself at 11. That behavior is also your TCPA calling-hours enforcement, so resist the urge to disable it in production.

The checklist that circulates in the VICIdial community — set call time to 24-hour for a test, filter to NONE, confirm list and campaign are both active, confirm lead statuses are dialable — is community material, but each gate it tests is real in the hopper script. Two more dials to check: hopper level is the count the script keeps the hopper filled to on each minutely run, and with auto-scaling enabled the effective level is derived from logged-in agents times dial level, with the configured level as the floor.

Dead air on connect: AMD timing vs. a real audio fault

Dead air after a contact says “hello” has two very different causes, and the first diagnostic question is whether answering machine detection is in the path.

AMD cannot begin classifying until the carrier signals Answer — the VICIdial project’s own Astricon material states detection cannot start until after the Answer signal. Every moment of analysis after that point is silence the contact hears. That is the core trade-off, in the project lead’s framing: the longer the analysis time, the better the accuracy — and the more likely the customer hangs up. The built-in Asterisk app_amd is subject to the same trade-off, and loud background noise on the contact’s end degrades every AMD engine.

So the test is simple: place a manual call with AMD off. If the dead air disappears, your fix is tuning the analysis window and routing, covered in our answering machine detection guide. If silence persists on a manual AMD-off call, you have an audio-path problem — usually NAT advertising a private address in the SDP — which the one-way audio deep dive owns.

Dropped calls: read the hangup cause before touching config

When calls drop, Asterisk already recorded why — the SIP response maps to a hangup cause. In Asterisk’s mapping, a carrier 403 becomes CALL REJECTED (cause 21) and a 503 becomes CONGESTION (cause 34). A rejection points at account and authorization issues; congestion points at routes and rate limits. If blocked-call codes appear, SIP 603+ (“Network Blocked”) is the FCC’s standard blocked-call code, mandatory since March 25, 2026 — our 603 guide decodes the Reason header.

One trap deserves flagging: Asterisk’s AUTO-CONGEST is not a 503 — it is a no-response INVITE timer, and no response points at reachability (a firewall, IP allowlisting, an unresponsive proxy), not at campaign settings. The 503 guide’s AUTO-CONGEST section untangles the two.

Drops that consistently hit at a fixed interval mid-call are a different family — usually session-timer or NAT keepalive issues, covered in the trunk setup guide’s troubleshooting section.

Proving a symptom is carrier-side before blaming config

Some symptoms live outside your servers no matter what you tune. The honest way to establish that is an A/B test: split the same campaign, the same lead-list segment, and the same caller IDs across two trunks, and compare — the backup carrier and failover guide covers standing up that second trunk. If the symptom follows the trunk — drops, dead air, failed connects concentrated on one route — it’s the route. If it follows the campaign regardless of trunk, it’s your configuration.

Post-dial delay is the cleanest carrier-side measurement: time from INVITE to the first ringing response (180 or 183). The post-dial delay guide covers how to measure it, the threshold carriers treat as troubleshooting territory, and what a dialer should tolerate.

Spam labeling is carrier-side by definition: flagging is proprietary to each carrier’s analytics engine and keyed to the caller-ID number. The VICIdial project reported in its 2021 Astricon materials that as little as five minutes and 200 calls flagged a CID, and that flags took 2–21 days to clear after a number was retired. No dialer setting fixes that — remediation and attestation signing do, as the spam label guide walks through.

When the A/B test convicts the route, the fix is a carrier built for dialer traffic. SIPNEX is an FCC-licensed carrier signing its own STIR/SHAKEN A-level attestation, with 12/6 billing built for VICIdial operations.

Frequently asked questions

Where should VICIdial troubleshooting start when the hopper is empty?

The cron entry for the hopper script — it must run every minute, and a stalled cron loads nothing regardless of campaign settings. Then walk the gates: campaign active, lists attached and active, lead statuses in the campaign’s dial statuses, lead filter not over-excluding, and local call time — leads outside their local calling window are never loaded, so timezone-heavy lists empty the hopper at certain hours by design.

What troubleshooting step proves a VICIdial problem is carrier-side?

An A/B trunk test: same campaign, same lead segment, same caller IDs, split across two carriers. If the symptom follows the trunk, the route is at fault; if it follows the campaign on both trunks, it’s your configuration. Measure post-dial delay and compare drop rates per trunk over the same hours — a per-route difference on identical traffic is the evidence a carrier’s support desk can’t argue with.

Is dead air on connect an AMD problem or a carrier troubleshooting issue?

Test with a manual, AMD-off call — that one dial separates the two. AMD can’t start analyzing until the carrier signals Answer, so its analysis window is silence the contact hears; if the manual call is clean, tune AMD. If silence persists without AMD, it’s an audio-path fault — typically NAT advertising a private address in the SDP — and belongs to network troubleshooting, not dialer tuning.

How do SIP response codes speed up VICIdial troubleshooting?

They name the failing layer before you touch anything. A 403 means the carrier refused the call — authorization, caller ID, or account limits. A 503 means no route or a rate limit. A 603+ with “Network Blocked” means analytics blocking downstream. And no response at all means reachability, not rejection — the 503 guide separates a real 503 from Asterisk’s AUTO-CONGEST. Each code family has its own fix path.

---

Symptom still standing after the config checks? Run the A/B test against a trunk built for dialers: FCC-licensed, A-level attestation, 12/6 billing — VICIdial carrier service or (833) 665-2220.