Mautic Error Troubleshooting in 4 Steps

Troubleshooting Mautic is not usually simple, but it helps a lot if you know what to look for.
These 4 steps will get you there most of the time:  

1) Check ALL your logs.
2) Check the Mautic output on your browser.
3) Search the Internet, especially Github.
4) Report your findings.

---

Before you start your Mautic troubleshooting venture,

It is always good to make sure the problem actually exists and it’s not a ghost from the past…
For that, you need to clear your Mautic cache. Clearing your Mautic cache has a very slim chance of fixing your problem but it makes sure your Mautic server is not fooled by smoke and mirrors (the cache). Besides, you don’t want to spend the next few hours troubleshooting a problem that doesn’t really exist, do you?

Another common issue that’s really annoying and simple to discard is a database that’s not up to date, again that’s probably not going to fix anything, but it will make sure you are solving the right issue and nothing else is masking the errors.

To clear the Mautic cache you can simply delete the folder where the cache is located by issuing this command:

 rm -rf /var/www/html/app/cache/*
Don’t worry, Mautic will take care of re-creating the folders and files as they are needed.

To make sure your database schema is updated:

Point your browser to  http(s)://[your-mautic-url]/s/update/schema

Mautic will make sure your DB is up to date and make any needed changes if it’s not.

If that fixed your problem, congratulations, most often than not it won’t, but with those 2 pre-troubleshooting steps you have achieved 2 things:

a) You made sure you’re looking at the real problem and not a reflection of other issues.
b) You have established a common baseline to work with.

1) Check ALL your logs

If there is an issue, 99% of the times there’s also a trace somewhere telling you what the problem is, common places to look for are (on an Ubuntu System, other OSs might have different locations):

The Mautic log:
You can check the latest events within the Mautic UI if you go to Settings > System Info > Log
If you can’t access the UI or you want to take a look at the full logs, you can check the logs in your server on /var/www/html/app/logs/

 The Apache / PHP log: /var/log/apache2/

The Mysql log: located at /var/log/mysql/

The System log: located at /var/log/syslog/

The error msgs will probably look cryptic to you, here’s how to interpret them:

All error msgs follow a similar structure:

DATE/TIME – ERROR TYPE – WHO’S COMPLAINING – ERROR MSG – ERROR LOCATION – DETAILS

The order may vary slightly but this is a very widely spread and common standard.

Some of this data is relative to your server only, some of the data is generic to the error itself, and this is what’s useful for you to do your research.

DATE/TIME: This is important data for yourself, but totally irrelevant to find help.

ERROR TYPE: 99% of the times you can discard “WARNING” msgs, you need to look for “ERROR” and “CRITICAL” entries.

WHO’S COMPLAINING: This tells you which part of your system is logging the error, your server has many pieces and layers of software, knowing which one is logging the error gives you important clues about what the problem is about.

ERROR MSG: This is the bread of the issue, this is exactly what went wrong.

ERROR LOCATION: Most of the time there will be a process name or a file name here, this is the process or the file that was being executed at the time when the error happened, if you are lucky, you might even get a line number, telling you exactly which piece of code is causing the error. Don’t be fooled, the line where the error happened is not always the real culprit.

DETAILS: Most of the time a construct made with all or some of the previous information, the “good stuff” is usually found towards the end of the line…

2) Check the Mautic output on your browser

Many times you will also find clues looking at the output Mautic sends to your browser, especially If your issue is UI related, and sometimes if there’s a networking issue, you can find out more by using the developer console on Chrome.

3) Search the internet, especially GitHub

Once you have removed the useless information, Google the error messages found on the previous steps, use Google to search the Internet in order to find anything anyone else has posted anywhere about your issue or a similar one.
Sometimes you’ll be lucky and find a solution right ahead, most of the times you won’t, and you will have to keep searching by extrapolating what happens to you and comparing it to what happened in other cases. Don’t narrow yourself exclusively to Mautic related issues and answers, sometimes the solution is elsewhere…

4) Report your findings

If you found the solution, you might want to post a comment somewhere to document your problem and how you solved it, the next person having your same issue will be very happy that you did, and this is exactly why and how you found the solution to your own issue in the first place, this is what makes the Internet a great place, don’t be lazy and write a few lines!

If you didn’t find the solution, but you have a clear idea of what’s causing the problem, open a bug in Github or ask in Slack (or maybe both).

About 80% of the times the solution is already out there, but there is a 20% chance that you found a new bug, in which case you can fix it yourself if you are a developer or just report it on Github and wait until a solution is found and coded. Remember to always post something in Github to let the devs know about the issue and also so you get notified when there’s news.

These 4 steps should help you rid of 99.9% of Mautic issues, however in the rare chance that there are no errors in any of the logs or for some reason you need to further troubleshoot Mautic, you can edit your local.php file and add  'debug' => true, , then delete the cache and Mautic will start spitting out all sorts of extra information about it’s runtime.

I will be adding soon an example of how to interpret an error msg, for today this is what I have got,

As always, if you have any question, observation or correction to point out, please do so in the comments here below. 

Good luck troubleshooting!

PD: Thank you Peter for the debug  = true remark.