Mautic troubleshooting: fix emails, campaigns and errors

Most Mautic problems fall into four groups: emails that never leave, campaigns that never fire, tracking that records nothing, and 500 errors. Nearly all of them share a root cause, a stopped cron job or a wrong server setting. Mautic is a self-hosted application built around queues, so the symptom you see in the interface is rarely the cause. The cause sits in the log, the crontab or the SMTP settings. This Mautic troubleshooting guide is about diagnosis: what to check when something that used to work stops working.

When a Mautic instance I run in production stops sending, I don't start clicking around the interface. I open the log first, and in my experience that's where the answer is about 80% of the time.

Start Mautic troubleshooting with the log

In current Mautic versions, application logs live in var/logs/, and the production file is mautic_prod.log. On the server, the full path usually looks like /var/www/mautic/var/logs/mautic_prod.log.

Without terminal access, read the last lines in the gear menu under System Info. Either way, search for ERROR and CRITICAL. Those lines name the exact exception (SMTP failure, database error, denied permission), and it almost always explains what you see on screen. Only after reading the log do you know whether you're facing an email, cron or server problem.

Problem 1: emails are not sending

Email delivery is the most reported Mautic troubleshooting case, and it rarely has a single cause. Work through the checks below in order.

The queue and the send cron job

Mautic can send in queue (spool) mode. Instead of delivering each email right away, it stores messages and lets the mautic:emails:send cron job hand the batch to SMTP. If that command never runs, emails pile up and nothing goes out. To flush the queue right now, run:

php bin/console mautic:emails:send --no-interaction

If that clears it, the cron job was the problem, so schedule the command in the crontab. With synchronous sending (no queue) you don't need this cron job at all, and the main suspect becomes SMTP.

SMTP settings and provider limits

Under Configuration > Email Settings, check the host, port, username and password, then send a test email to confirm them. Use a transactional provider with a good reputation, such as Amazon SES, Mailgun, SendGrid or Postmark, and keep an eye on its limits. The Amazon SES sandbox, for example, delivers only 200 messages per 24-hour period, and only to verified addresses. Until your account leaves the sandbox, SES blocks everything else and Mautic writes the error to the log.

The email type

Emails used inside campaigns must be created as Template Email. A Segment Email is a one-off broadcast and can't be picked in a campaign's Send Email action. Check the Type column under Channels > Emails. The full builder walkthrough is in the Mautic campaigns guide.

Problem 2: campaigns don't fire

After SMTP, campaign cron jobs are the second most common cause in Mautic troubleshooting. Campaigns depend on three commands that must run in the right order, because each one uses the result of the one before:

1. mautic:segments:update recalculates who belongs to each segment.
2. mautic:campaigns:rebuild decides who enters or leaves each campaign based on those segments.
3. mautic:campaigns:trigger runs the pending actions (send an email, apply a tag, adjust points).

If one of them doesn't run, or they run out of order, the contact still enters the campaign but no action happens. That's the classic "I set everything up and nothing fires" case. Check what is scheduled with:

crontab -l -u www-data

Replace www-data with your web server user. If the list is empty or the Mautic commands aren't in it, the cron jobs aren't configured. The full list, the intervals and the reason for the order are in Mautic cron jobs. Wrap each line in flock so one run can't start before the previous one finishes.

Problem 3: tracking doesn't record visitors

Mautic follows site visits through a tracking script, mtc.js, which has to be on every page. When it records nothing, check these in order:

• The snippet sits before </body> on all pages. The safest way to get it is to copy a form's embed code, which already includes tracking.
• The Mautic URL in the script is correct and publicly reachable.
• Both the site and Mautic run on HTTPS. Modern browsers block mixed content, such as an HTTPS site loading a script over HTTP.
• No cache plugin or CDN strips or defers the script.
• Ad blockers are off while you test. uBlock and similar extensions often block mtc.js.

Tracking only ties a visit to a contact after the person submits a form or clicks a tracked email link. Until then the visit is anonymous, which is expected. How those visits turn into points is covered in Mautic lead scoring.

Problem 4: contacts don't enter segments

The mautic:segments:update cron job recalculates dynamic segments. If a contact that should be in a segment isn't there:

• Confirm that mautic:segments:update is running. Segments do not update in real time.
• Review the segment filters, paying attention to the operators (equals, contains, greater than) and the exact field values.
• Force a recalculation now instead of waiting for the next cycle:

php bin/console mautic:segments:update --no-interaction

If the contact joins the segment after that manual run, you've found it: the scheduled cron job was missing.

Problem 5: 500 errors, cache and permissions

A 500 error often shows up right after a version upgrade. The log shows the real exception, but the three most frequent causes are these:

• Stale cache. Clear it with php bin/console cache:clear.
• Permissions on var/. The var/cache, var/logs and var/spool folders must be writable by the web server user. Fix the owner with chown -R www-data:www-data var/, using the right user for your install.
• Pending database migrations. An unfinished upgrade breaks the dashboard. Run php bin/console doctrine:migrations:migrate --no-interaction to apply them.

Back up before every upgrade: dump the database with mysqldump and copy app/config and the media folder, keeping the copies off the server. The core usually upgrades cleanly. Third-party plugins and customizations are what tend to break.

Slow instances and failed imports

Large imports, or jobs that die halfway through, almost always hit a PHP limit. Raise the limits in php.ini and run heavy jobs from the command line instead of the interface, so you don't run into the web server's max_execution_time:

• memory_limit = 512M as a floor, or 1G for large databases
• max_execution_time = 300
• upload_max_filesize = 20M and post_max_size = 20M for CSV imports

For general speed, the cheapest gain is in PHP itself. Enable OPcache (opcache.enable=1 in php.ini), which keeps compiled bytecode in memory instead of recompiling the code on every request. Tracking and statistics tables also grow until they slow the database down, and mautic:maintenance:cleanup --days-old=365 removes the old rows. Schedule it weekly, and back up the database before the first run, because the deletion is permanent.

An aggressive cron schedule can also overload the server. Stagger the start times and process large databases in batches with --limit, for example mautic:campaigns:trigger --limit=100.

Emails landing in spam

When mail goes out but lands in spam, Mautic troubleshooting moves to DNS. Set up SPF, DKIM and DMARC records before the first send. SPF lists the servers allowed to send for your domain, DKIM signs each message, and DMARC tells mailbox providers what to do with mail that fails those checks. On a new domain or IP, warm up by raising volume gradually over a few weeks instead of mailing the whole list on day one.

Also fill in the plain text version of every HTML email, since many servers treat a missing one as a spam signal. Then schedule mautic:email:fetch to process bounces. Returned addresses get marked as invalid instead of hurting your domain's reputation with every send.

Mautic troubleshooting quick reference

Mautic troubleshooting FAQ

Why are my Mautic emails stuck in the queue?

In queue mode, Mautic leaves each email in the spool and the mautic:emails:send cron job hands it to SMTP. If it never runs, the queue grows. Run php bin/console mautic:emails:send by hand to flush it, then schedule the command in the crontab. If nothing goes out even then, look at SMTP credentials or a provider limit. Check the log at var/logs/mautic_prod.log.

I set everything up, but the campaign doesn't fire. What do I check first?

It is almost always cron. Campaigns depend on three commands in the right order: mautic:segments:update, then mautic:campaigns:rebuild and finally mautic:campaigns:trigger. If one doesn't run or they run out of order, the contact enters the campaign but no action happens. Check what is scheduled with crontab -l -u www-data, and confirm the campaign email was created as a Template Email rather than a Segment Email.

Why do Mautic emails go to spam?

The usual causes are a domain without SPF, DKIM and DMARC records in DNS, an IP with a poor reputation, spammy content, a high bounce rate or a missing unsubscribe link. Set up the authentication records first, then send through a transactional SMTP provider with a good reputation, such as Amazon SES, Mailgun or Postmark.

Mautic is slow or throwing 500 errors. How do I diagnose it?

Start with the log at var/logs/mautic_prod.log, which shows the real exception. A 500 error is usually low PHP memory, permissions on var/ or a pending migration after an upgrade. Slowness usually comes from an undersized server, a database without indexes or caching turned off. Plan for at least 2 GB of RAM and enable a cache such as Redis.

The order that saves time

Good Mautic troubleshooting follows the same order every time: read the log before touching any setting, confirm the cron jobs, and only then move on to SMTP, tracking or permissions. With the cron jobs in order, authenticated SMTP, tracking over HTTPS and a writable var/ folder, Mautic runs steadily for months without intervention.

If you're setting up a new instance, start with how to install Mautic. When a problem won't go away, the official Mautic documentation is the reference for any Mautic troubleshooting, and it has an active community around it.