Common VICIdial install errors and fixes

Most VICIdial installs fail at one of four points. The Perl dependency layer, the Asterisk compile, the database grants, or SELinux. None of them are mysterious once you know what the error message is actually telling you.

Missing Perl modules

VICIdial's back-end is a fleet of Perl scripts — the dialer, the Keepalive loop, the listen-loop processes. They depend on a long list of CPAN modules: DBI, DBD::mysql, Net::Telnet, Time::HiRes, Switch, and more. The install script dies with "Can't locate Foo/Bar.pm in @INC" the moment one is absent.

The fix is to install the module by hand and re-run. Prefer your distro's packaged version (libdbi-perl, libnet-telnet-perl on Debian-family) and fall back to cpanm only when no package exists. DBD::mysql is the usual holdout because it needs the MySQL client headers present before it will build. Install those first, then the module.

Asterisk compile failures

VICIdial ships a patched Asterisk source, and compiling it from scratch is where a clean install most often breaks. The two recurring causes are a missing dev library and a wrong kernel/header pairing. If menuselect can't find a feature you need, or make stops on a header it can't include, the cause is almost always a missing -dev package: libncurses, libnewt, libssl, libxml2, or uuid.

Read the last 20 lines of the make output, not the first. The first error is usually noise; the real stop is near the bottom. Install the named dev package, run make clean, and rebuild. Don't skip make clean — a half-built tree carries stale object files that produce confusing link errors on the second pass.

flowchart TD
  A[Run install script] --> B{Perl modules present}
  B -- no --> C[Install CPAN module and rerun]
  B -- yes --> D{Asterisk compiles}
  D -- no --> E[Add missing dev lib then make clean]
  D -- yes --> F{DB grants work}
  F -- no --> G[Fix MySQL user and host grant]
  F -- yes --> H{SELinux blocking}
  H -- yes --> I[Set permissive or add policy]
  H -- no --> J[VICIdial admin loads]

MySQL grant problems

After the schema loads, the dialer and the web admin both connect as the cron user. "Access denied for user" means the grant doesn't match. The common trap is host scope: a grant for 'cron'@'localhost' won't authorize a connection that arrives over the loopback IP as 'cron'@'127.0.0.1', and a multi-server build needs grants for every server's address, not just localhost.

Confirm the database name, user, and password in astguiclient.conf match the grant you actually created, then flush privileges. On newer MariaDB the default auth plugin can also reject a plain-password connection — set the user to mysql_native_password if the dialer logs in fine from the shell but not from Perl.

SELinux and the silent blocks

On RHEL-family systems SELinux in enforcing mode quietly blocks Asterisk from writing recordings, opening its AMI (Asterisk Manager Interface) port, or reading a Conf file it expects. The symptom is maddening: everything looks installed, nothing logs an error, and calls just don't connect. Check the audit log for AVC denials before you blame the config.

For a single-purpose dialer box, setting SELinux permissive is the pragmatic move; if your policy requires enforcing, generate a targeted module from the denials with audit2allow rather than disabling it outright. Either way, fix it before you go further — a half-blocked Asterisk produces RTP and signaling faults that look like network problems but aren't.

Work the order, not the symptom

These four failures cascade. A broken grant looks like an Asterisk problem; an SELinux block looks like a carrier problem. Solve them in dependency order — Perl, then Asterisk, then MySQL, then SELinux — and most installs come up clean. Our full install guide walks the whole build, and the install-script walkthrough shows exactly where each of these checks lives.

Or skip the whole sequence. We hand you a secured VICIdial box with the Perl layer, Asterisk, the database, and SELinux already sorted — provisioned in under 40 seconds, with root SSH so it stays your box. See plans on our pricing page.