For dialer teams running VICIdial out of Metro Manila, Cebu, Davao, Quezon City, or Makati, the hopper is one of those parts of the VICIdial Hopper Issues system nobody thinks about until it stops working. It sits quietly in the background, pulling qualified leads into a holding table and handing them to agents the moment a campaign needs one. When it works, nobody notices it.
When it stops, the symptoms look confusing: agents are logged in, the list has thousands of records, and yet nothing happens. Dial Next Number does nothing. The screen does not update. No call goes out.
This kind of stall is one of the more common support requests we see from businesses across the Philippines running their own VICIdial installation, and it almost always traces back to one of a handful of causes: leads that never made it into the system correctly, a campaign setting that quietly blocks delivery, or a database in a state that the dialer was never designed to run on.
This article walks through how the hopper is supposed to behave, what a broken hopper actually looks like from the database side, and a practical order of checks to work through before assuming the worst.
What the VICIdial Hopper Actually Does
The hopper is the table VICIdial uses to stage leads that are ready to be called right now. A background script, commonly AST_VDhopper.pl, scans the active campaign’s lead list on a schedule, applies the campaign’s filtering rules, and inserts a working set of eligible records into vicidial_hopper. Agents and the auto dialer then pull from that smaller, pre-qualified table instead of scanning the full list on every call attempt.
That separation matters for troubleshooting. A campaign can have thousands of records in vicidial_list and still show nothing in vicidial_hopper, because the two tables answer different questions. vicidial_list answers “what leads exist.” vicidial_hopper answers “what leads are eligible to be called right now, for this campaign, under its current rules.” A stall can happen at either point, and the fix is different depending on which one is empty.
Symptom 1: The hopper stays empty even though the list is full
This is the most common starting point for a hopper complaint, and it is worth checking before touching anything else. Run a quick count against the list itself:
SELECT COUNT(*) FROM vicidial_list;If that number is unexpectedly low, or zero, the hopper was never going to fill in the first place, because there is nothing eligible for it to pull from. In one production case we reviewed, an import that appeared to complete successfully in the upload wizard actually inserted zero records, with the import log reporting record 0 BAD-PHONE across every format tried, including plain phone_number plus phone_code columns and full E164 formatted numbers.
The upload screen showed success. The database told a different story. A few things worth checking when the list count does not match expectations:
- Whether the phone number column in the source file matches the field the import wizard expects for the selected format
- Whether a custom lead layout is quietly rejecting or reformatting the phone field on the way in
- Whether the list ID used in the upload actually belongs to the campaign being tested against
- If the import itself is failing silently, no amount of hopper troubleshooting further down the chain will fix the underlying problem.
Confirm records exist and are attached to the right list before moving on.
Symptom 2: The hopper fills, but nothing gets dialed
This is a different and, in some ways, more frustrating problem, because it looks like everything should be working. A direct query against the hopper table confirms leads are present:
SELECT COUNT(*) FROM vicidial_hopper WHERE campaign_id=’CAMPAIGN_ID’;
If that returns a positive number, even a small one, the hopper script did its job. The stall is happening after that point, in one of two places.
The first is the campaign’s dial level setting. auto_dial_level controls how aggressively the system places outbound calls relative to available agents. If that value is set to zero, the auto dialer will not originate calls on its own, regardless of how many leads sit in the hopper.
This is easy to overlook because it is a single numeric field buried in campaign detail settings, and it produces no error message. The system simply does nothing, which reads as broken even though it is behaving exactly as configured.
The second, and less obvious, cause sits at the database level. A query against system_settings for db_schema_version should return a version number in the thousands for any current VICIdial Hopper Issues release.
A result of zero indicates the schema is not at the version the installed code expects, which typically happens when an upgrade was started and never finished, or when a custom installation skipped schema migration steps.
On systems in that state, PHP warnings such as Undefined variable errors tend to show up across admin.php, admin_header.php, and admin_listloader_fourth_gen.php, because the code is referencing settings that the schema does not yet define in the expected form. Hopper logic, campaign lead selection, and dial control all depend on that same schema, so a mismatch here can produce exactly this kind of silent stall.
Symptom 3: Leads are in the hopper, but agents are told none are available
This variation is particularly confusing because the numbers look healthy on paper. A campaign might show 6397 leads available in the list, and a hopper count of 1 for the same campaign, yet an agent clicking Dial Next Number sees “No leads available” or the button simply does nothing. When the hopper has at least one eligible record and the agent still cannot pull it, the cause is usually in how the campaign is matching agents to leads rather than in the hopper contents themselves.
Two areas worth checking here:
Agent status at the moment of the attempt. A quick check against vicidial_live_agents will show whether the agent session is actually in a state the campaign considers ready to receive a lead. It is not unusual to find an agent showing PAUSED in the database even though the interface appears to show them as available, which points to a state sync issue between the agent screen and the underlying session table.
Lead filtering rules on the campaign, including any custom lead layout or custom field mapping. If the fields VICIdial Hopper Issues do not line up with how the data was actually imported, the campaign’s own filters can exclude leads that technically exist in the hopper, because the system cannot confirm they meet the delivery criteria it is checking against.
A related pattern worth watching for: agents dropping back to pause on their own
Some hopper-adjacent tickets turn out to be agent state problems wearing hopper symptoms. An agent resumes from a pause, appears active for a short window, and then reverts to PAUSED without touching anything.
From the hopper’s perspective this looks identical to a delivery failure, because a paused agent will never be offered a lead no matter how full the hopper is. If this pattern shows up alongside a stalled hopper, it is worth checking agent session logs and conference state before spending more time on the hopper query itself, since fixing the hopper will not help an agent the campaign considers unavailable.
A step-by-step VICIdial Hopper Issues order of checks
When a hopper complaint comes in, working through these checks in order tends to isolate the cause faster than jumping between settings screens:
- Confirm the list actually has records: SELECT COUNT(*) FROM vicidial_list. If this is low or zero, go back to the import, not the hopper.
- Confirm the hopper itself for the specific campaign: SELECT COUNT(*) FROM vicidial_hopper WHERE campaign_id=’CAMPAIGN_ID’. This tells you whether the hopper script ran and found eligible leads.
- Check db_schema_version in system_settings. Anything far below the expected range for the installed VICIdial version is a signal to stop and address the schema before chasing individual symptoms.
- Check the campaign’s auto_dial_level. A value of zero explains a fully populated hopper with zero outbound activity on its own.
- Check vicidial_live_agents for the affected agents. Confirm the database agrees with what the agent’s screen is showing.
- Review the custom lead layout attached to the campaign against the actual columns in the imported data, especially if leads exist but are being reported as unavailable to agents.
- Working through these in sequence avoids the common trap of adjusting campaign settings first, which can mask a schema or import problem rather than fixing it.
Why the database schema deserves attention first
It is tempting to treat a db_schema_version of zero as a side detail and focus on the more visible symptoms, like a paused agent or an empty hopper. In practice, schema mismatch tends to be the common thread underneath several unrelated-looking problems at once: import failures, PHP warnings across admin screens, inconsistent pause behavior, and a hopper that fills but never triggers a call.
If an installation shows PHP undefined variable warnings across multiple admin modules alongside a hopper stall, it is worth confirming the schema version before spending time on any single symptom in isolation, since a partial upgrade can leave the underlying tables in a state the application code was never meant to run against.
How KingAsterisk approaches a stalled hopper
Our process for a hopper complaint from a Philippine business running VICIdial starts with the same sequence outlined above: confirm the list, confirm the hopper, confirm the schema, confirm the campaign settings, confirm the agent state.
Most hopper tickets resolve at one of those first four checks. The ones that do not usually point to a deeper installation issue, most often an incomplete upgrade or a custom lead layout that was configured before the schema was fully validated.
We work with businesses in Metro Manila, Quezon City, Makati, Cebu, and Davao running their own VICIdial systems, and the pattern across most support requests is the same: the dialer looks broken from the agent’s chair, but the actual cause is a data or configuration issue several layers below the interface.
Getting a clear read on vicidial_list, vicidial_hopper, and system_settings before changing anything saves the back-and-forth of adjusting settings that were never the problem.
Frequently asked questions
Why did my lead import say it completed but vicidial_list is still empty❓
This typically means the import wizard rejected the records during validation, often flagged as a phone number format issue, even though the upload screen reported success. Confirm the actual row count with a direct query rather than relying on the upload confirmation message.
What does db_schema_version=0 mean in VICIdial Hopper Issues❓
It means the installed database schema does not match what the running VICIdial code expects, which usually happens when an upgrade was interrupted or never completed. This mismatch can affect import, hopper, and dialing behavior at the same time, and is worth resolving before troubleshooting individual symptoms.
Why does an agent keep going back to paused automatically❓
This is generally an agent session or conference state issue rather than a hopper problem. Checking vicidial_live_agents directly will show whether the database and the agent’s screen actually agree on their current status.
Why does an agent see “no leads available” when the hopper has leads❓
This usually comes down to campaign filtering rules or a custom lead layout that does not match how the data was imported, which can cause the campaign to exclude leads that technically exist in the hopper.
Get your Vicidial running the way it should
A stalled hopper is rarely a single broken switch. It is usually the visible symptom of something upstream, whether that is an import that silently failed, a campaign setting left at its default, or a schema that never finished migrating.
If your team in Manila, Cebu, Davao, or anywhere else in the Philippines is dealing with VICIdial Hopper Issues that will not load or will not release leads, KingAsterisk can review the installation, walk through the same checks outlined above against your actual database, and identify exactly where the chain is breaking. Reach out to KingAsterisk to get your campaigns moving again.
