Troubleshooting the ‘site is currently offline due to encountering an error’ in Mautic

We all know that gut-sinking feeling when you’ve just installed or updated Mautic or maybe updated a plugin and suddenly instead of seeing your Mautic user interface, you are presented with the message:

The site is currently offline due to encountering an error. If the problem persists, please contact the system administrator.

Sometimes accompanied by our cheerful friend, the Mautibot.

So, how do you go about troubleshooting this error?

Let’s start with what causes the error to arise in the first place.

Common causes of the error:

Server configuration problems

Incorrect permissions
PHP version mismatches
Improper server configuration

Resource limitations

Insufficient memory, CPU or disk space in your hosting environment

Corrupted or inaccessible files or a failed update

Files may become corrupted or inaccessible if there are problems with your server’s hard drives
An update that hasn’t completed successfully

Database issues

Connection errors, corrupted tables or unsupported database types can prevent Mautic accessing the required information

How to resolve the most common problems

Find out exactly what the problem is

Check your Mautic logs

More often than not, the exact cause of the problem can be located in the Mautic log files. You will need this information to ask for support in the Community Forums, so check for this first.

Log files reside in the var/logs folder within your Mautic directory if you’re using Mautic 3.0 and later, or in app/logs for Mautic 2.x and earlier.
Check the log for the current day and look at the last entries. If you can’t tell which one relates to the error, reload the page and refresh the log file.
Look at the actual log message - it can often point you towards the problem, or at least give you something to search for on the forums.

Check your server logs

Server logs can give you critical information as to what caused Mautic to crash.

This error is usually to do with something being broken in Mautic, but sometimes if you can’t find anything in the Mautic logs, the problem has occurred before the request got to Mautic - e.g. it’s something to do with your server configuration - so this step will help you to dig deeper.

Generally speaking you’ll find the logs in these locations, but it can vary based on how your server is configured:

Apache - typically located in var/log/apache2/error.log
NGINX - typically located in var/log/nginx/error.log

Verify your environment meets requirements

Check your server software meets Mautic’s requirements

Sometimes hosting providers - especially on shared hosting - may update their infrastructure without warning, adding or removing support for new versions of PHP, MySQL/MariaDB and so forth.

This might mean that the software on your server has become incompatible with Mautic - often without any warning.

Check the versions at https://mautic.org/download/requirements and verify the versions running in your hosting environments match and do not exceed those listed.

You can usually check the versions using commands like php -v or mysql -V. Refer to your hosting provider’s control panel, which might also allow you to set the PHP version of specific folders.

Ensure your server is adequately resourced

Sometimes you may see errors that talk about trying to allocate <some number> of resources. These usually mean that your server has run out of available memory when trying to process a task.

Please refer to this documentation resource to understand more about resource limits and how to work with them in Mautic: https://docs.mautic.org/en/5.x/troubleshooting/working_with_resource_limits.html.

Check permissions and ownership of files and folders

Sometimes - especially after an update or when working via FTP or command line - files and folders can end up being owned by a user which doesn’t have the same permissions as the system user which runs the Mautic application. This can mean that files and folders become inaccessible, leading to critical errors.

In this case you will likely see permission-related errors in the logs.

Please review this documentation article which explains the topic in more detail and also how to resolve it: https://docs.mautic.org/en/5.x/troubleshooting/file_ownership_permissions.html

Check you have the correct docroot for your virtual host

If you installed Mautic using the Recommended Project method with Composer, or you’ve followed the documentation to switch to Composer, the Mautic application is moved to a folder - /docroot by default - to improve security, which is where the application itself runs from.

If you don’t update your root path settings to use this as the project root, it will cause errors about autoload.php not loading and Mautic will not load, as it will be trying to load Mautic from the wrong location.

Check your database connection

Verify the credentials in config/local.php (Mautic 4.0 and later) or app/config/local.php file (Mautic 3.x and earlier) are correct and ensure that your database server is running, accepting connections and isn’t overloaded.

Check for corrupted files

If you’ve started a Mautic update and it crashed part-way through or something isn’t right with the files on your server, it’s possible they’ve become corrupted.

Please follow the documentation here: https://docs.mautic.org/en/5.x/troubleshooting/troubleshooting.html to recover from a failed update.

How to prevent this happening again

There are a few things which can help to prevent these problems from happening again.

Control your own resources - A big downside of using shared hosting is that you have little to no control over your infrastructure.

If the problem arose due to a configuration or resource issue or due to the way the environment is configured, consider moving to a Virtual Private Server or a Dedicated Server where you can control your environment fully.

Some providers offer managed VPS services where they take care of the underlying server updates but you control the versions in use for your application, which is a good halfway house if you don’t want the responsibility of setting up and securing your server.
Backup, backup, backup! We can’t emphasize enough the importance of backing up your Mautic instance - both the files and the database - and making sure your backups restore correctly by having a local or staging server.

Any time you make changes like updating Mautic, installing a new plugin or changing significant configurations, it’s important you take and test a backup first. That second part is important - an untested backup is not a backup at all. Those extra few minutes will save you hours of heartache if a problem arises later down the road.

In an ideal world, try to have a local or staging server where you can test updates in a near-live environment before carrying them out on your production server.
Monitor server resources - applications like Nagios, Zabbix, New Relic and Datadog (for example) make it easy for you to monitor your server and proactively alert you if there are resource issues or bottlenecks that are causing problems.

This can also help you to track back through recurring incidents to see when they started to happen.
Update regularly - it’s important that you don’t get too out of date with Mautic releases, as they often contain important bug fixes, security updates and improvements.

The further behind you get, the harder it is to update when the time comes. Try not to get more than one minor release behind (e.g. when 5.2 is released you shouldn’t be on a version older than 5.1).

How to get help if you’re still stuck

Mautic has a vibrant, welcoming community on our Forums who are here to help you by giving up their free time to support other users. We have certain expectations that you should take into consideration when asking for support:

Search first, then post

Our forums have pretty good technology behind the scenes which will show you some relevant forum posts as you’re typing, but it’s always a good idea to search the forum first, before asking for help. If you’re new to the forums you’ll need to spend time reading threads before you’re able to make a new post, so use the time to see if someone else had a problem like yours. Things to search for include:

The specific error that you found in your Mautic / Server logs
A description of what you were doing before it broke
Mautic (xxx) update failed (where xxx is your version)

Use the post template

In the Support categories we have a post template which asks you to include relevant information. Always use it - this means that people who are giving up their free time to help you have all the information they need to see what the problem might be.

Be patient, be kind, be considerate

Community support is provided by people like you who happen to give up their free time to help others.

Demanding an immediate fix to your problem or being impatient if someone hasn’t replied isn’t going to encourage people to help you.

Perhaps see if you are able to answer some existing questions while you wait for a response. Ensure you’ve provided as much detail as you possibly can, including the steps you’ve taken to troubleshoot.

When someone does respond, please assume positive intent and be kind, courteous and respectful - even if they’re asking you to do something you’ve already done or that doesn’t seem relevant. Refer to our Code of Conduct for how we expect people to behave in our community.

Seek professional help if you need a quicker resolution

If you’re using Mautic in a professional setting and/or you need a faster response, we recommend seeking professional help. You can do this by:

Posting in the Commercial forum category if you’d like to financially support someone to help you with the issue you’re experiencing
Reaching out to one of our Partners, Members or Sponsors