Sorry, there was a problem we could not recover from.

The server returned a "500 - Whoops, looks like something went wrong."

Gee, thanks, Joomla. I can see that. My site isn't working. Want to give me any further information so I can fix the darned thing?

It's all just dreadfully unhelpful. Not only that, but it's a big ugly red screen. It's not even styled like my site any more. What have I done? Have I lost everything? Is all my work gone? Have I been hacked? Perhaps I shouldn't have pressed that button?

And I haven't got a clue how to solve it or what is wrong.

I could guess. I could frantically start praying to the Gods of Open Source to give me back my beautiful site.

Or perhaps you could take the approach I take. Loudly swearing at my computer and throwing a strop.

Perhaps you could try everything you could think of. Clearing cache. Rebooting your computer. The usual stuff that helps. Still not working right?

That's because this is a server issue. An annoying server issue.

Perhaps you ask your host. Perhaps they aren't much use either. Perhaps they give you some generic information that doesn't really help you. Let's be honest, some hosts know nothing of Joomla. So they don't give you advice of any worth.

And perhaps they check the error logs. "Sorry, the logs are not showing any errors, this must be a configuration problem with your CMS". Well… perhaps they're right. Perhaps it's not a PHP error. Perhaps it's something else they need to be looking for. Or you need to be looking for.

I've recorded a video taking you through these steps, it might make things clearer.

https://youtu.be/tumIyXVeFaQ

This troubleshooting document was originally created on the Square Balloon site, Joomla Experts for over 16 years.

So how do we fix this?

Let's start by getting Joomla to give us more information. We can't just start randomly investigating things, we need a clue.

Step 1. Turn on Joomla's Debug.

Let me be clear. This will resolve your issue on 99% of occasions. Or give you more of a clue. This is always step one and it always will be.

But how can I do that? I hear you scream at the screen in an exasperated voice.

Well, you're right. You can't log in. The administrator has an error 500 screen too!

No problems. This setting is controlled by the configuration.php file. You can either log in via FTP, or usually in your hosting there is a file manager. Either way is fine, it's the same difference.

Choose your method and navigate to your Joomla site. Mine is usually in the public_html folder. But it will depend on your server.

Find configuration.php and either search for or scroll until you find:

public $debug = false;

You will need to change this value to true

public $debug = true;

Once you have done that you can save the file. If you are using FTP, you should upload the file too. Once uploaded, refresh the FTP software (called an FTP client, e.g. FileZilla).

Now reopen the configuration.php file again and make sure your change is reflected. I have seen occasions when the file doesn't change. And on some servers it seems like it is a protected file. These are likely file permissions which should be updated.

JFYI, the permissions that are recommended by Joomla.org are 755 for directories and 644 for files.

Once configuration is completed configuration.php should have permissions of 444.

If FTP won't work you should use the file manager in your hosting e.g. cPanel has a file manager. There you should edit the configuration.php file. Set Joomla's debug option to true as per the instructions above and hit save.

Refresh your website.

You will see a LOT more information helping you understand what is causing the problem.

The first thing to do is to look through the whole page for the error message.

Don't forget to check the title in your browser tab too that can give you a clue.

Some common errors:

Cannot instantiate MySQL

If you look at the bottom of the screen it will say something like cannot access MySQL database. It's a clear sign one or all of the credentials are incorrect.

Likely the database name, database user, or database password is incorrect. Check the details with your host or in your hosting set up and make sure you have the same data in your configuration.php file.

Here are the three settings you need:

Database:

public $db = 'yourdatabase_name;

Database User:

public $user = yourdatabaseuser_name';

Database Password:

public $password = 'YOURPASSWORD;

If you see a file name referenced

The chances are it might show a file name. Perhaps you don't know what that file does, or you haven't edited it. Perhaps you are not a developer. That's ok. Take a deep breath, you don't need to be a developer.

What you do need to know is that file is causing the problem. You might want to check if it's related to a component, module or plugin that you have just installed or updated. If it is, perhaps there is a bug in the update. So you might want to be aware of that in case of future updates. You should always complete updates on a development/staging version of your site (a copy) to avoid any issues on the live site. It gives you more time to troubleshoot the issue and report it to the plugin developer if needed.

So how do you resolve this if you don't know PHP? Well, you don't. You simply disable that plugin. Why? I need that plugin I hear you exclaim?

Well, sure, but what we're doing here is making sure it is that plugin and not something else. Let's rule it out (or in) and then we can decide if it's a problem.

There are two ways to check this.

The first and I find the quickest, safest and most simple, is to rename that component, module or plugins folder.

Using FTP or a file manager navigate to find the folder.

Components are unsurprisingly in the "components" folder.

Each is named with com_ at the font of it. So all the Joomla articles are stored in a component called com_content. That component is unlikely to be the issue. There are thousands or millions of Joomla installs around the world. You can assume that any Joomla related issue would be fixed quickly if it was large enough to cause a 500 issue.

That said, if you do find an issue that is a genuine bug, you can report it on the Joomla Github or on the Joomla Issues Tracker. The two are linked so it doesn't really matter which one you report it on.

But for the purposes of this 500 error, let's assume it's not a core Joomla issue. Tempting as it may be to scream and shout at Joomla and blame it, it really is used all around the world successfully, if it was broken it would be broken for everyone.

Let's assume it's something you have installed or changed. Is there a component you just installed? Perhaps it's not compatible with this version of PHP? You could ask the developer the minimum PHP requirements. Perhaps it's not compatible with this version of Joomla but somehow it installed. Or perhaps you have upgraded from an older Joomla.

It doesn't matter really, like all of these steps, we are just trying to identify what the issue is.

Find the component and rename (not delete) the folder. I usually put two dashes as the front.

So for example if you see an error message and it looks like it might be related to com_akeebabackup I would the rename components folder to –-com_akeebabackup. That way the folder is no longer accessible by the code as it will be looking in the wrong place.

Once done, refresh your site.

If it works, you know something weird is going on with the component.

If nothing changes, i.e. it's still broken, then it may not be that component, I would rename it back to the original folder name.

One of the key things when performing these checks is that we are only checking one thing at a time.

For plugins they are in the plugins folder, but then usually in a sub folder like system or another sub folder. The clue will be in the error message you see.

Modules are in the modules folder and begin with mod_. The rules are the same regardless.

One final place you could see an error would be in an override. These are in templates/YourTemplateName/html/ and then in a sub-folder.

You should at least find enough information to identify it and then either fix it, or to ask a better question when asking others for help. I list all the places you can find help at the end of this document.

Step 2: A .htaccess issue?

Again, this is an easy one to check. As usual for this article, you don't actually have to understand .htaccess or any of the code inside. We just want to rule this out.

Either go to your files by FTP or your hosts file manager. Some hosts don't show hidden files, which .htaccess is considered. You need to make sure you can see the hidden file so you can edit it.

In my host's cPanel, at the top right, is a button called "settings." There is an option to "show hidden files."

Once you can see the .htaccess file, rename it (don't delete it). I usually call mine --.htaccess

Once renamed, refresh your page.

If it works, .htaccess is the issue, if it doesn't, the chances are it is not. If it's not the issue change your file name back to .htaccess and move on to the next step.

If it is the issue, there's an issue with your .htaccess file.

If you don't know a lot about .htaccess don't worry, I have a quick solution. You will need .htaccess in many cases as it controls the redirecting for SEF URLs. It also adds some important security features.

If you look in your Joomla directory using either FTP or your host's file manager, you will find a file called htaccess.txt.

This is a copy of the original Joomla .htaccess file. It's REALLY useful because you know that one usually works.

Rename this to .htaccess. Don't forget to remove the .txt at the end.

Refresh your site. Does the site load? You should also check if you change pages, do they work?

If so, you know something you changed in the .htaccess file broke things. You could copy and paste the contents into a help forum to ask for help. Or you could leave it as it is if it's working.

Step 3: Ask your host

Why not? They have the server; perhaps it is a setting they changed or some configuration option that you don't have access to. It's worth asking them. Some are not Joomla experts, so you might find they are not that helpful, but others are super helpful and solve the problem quickly.

Step 4: PHP Error Reporting

Often an error 500 won't show up on PHP error reporting. The error can happen before the PHP errors take place.

Nevertheless, if you have gotten this far, it wouldn't hurt to turn it on. You can either set this in your Joomla administrator under the server tab to maximum, or if you don't have access, you can use FTP or your host's file manager.

You are looking for this setting:

public $error_reporting = 'none';

You can change it to:

public $error_reporting = maximum';

Refresh your page to see if you now have any new error messages that could give you a clue as to what is wrong.

You can use these error messages on Google or in forums when asking for help. Make sure you copy the full and exact error message to allow people to help you as easily as possible.

Step 5: Check PHP Error Logs

Now that we have turned on error reporting you will likely see errors on the page. But in some cases they will be saved in error logs instead.

Your hosts will tell you how to access your PHP error logs. It's worth knowing this information so you can troubleshoot things without them as it's often quicker than raising a ticket. They could be in your host's login area/cPanel, or they may be a file on your server. You should ask your hosts about this.

Top Tip:

Look for lines that are dated today. The newest lines are the ones to pay attention to. They may give you a hint as to a component, module, plugin or file that has caused the issue.

Step 6: Rename Your Template's error.php

I have seen cases where the error.php page is causing the error. Ironic.

Don't forget to check your child theme error.php too.

Rename them e.g. –error.php and your error page will default to the Joomla error page.

Refresh your page. If the site loads normally, that's your issue, if not change the names back again.

Step 7: Gzip Issues?

Sometimes Gzip causes issues on certain servers. I would assume it could be because of either double gzipping or the gzip PHP module not being turned on (or Apache module, whatevs, it's a gzip issue).

Log in either via FTP or to your file manager on your host and open configuration.php

public $gzip = true;

change this to

public $gzip = false;

Don't forget other things like Akeeba's Admin tools can also Gzip things in their .htaccess manager. If you are following this guide, we already checked .htaccess earlier so that won't be the problem. But if you aren't following in order, it still could be, so it's worth knowing. It's also worth knowing if you use the .htaccess maker in Admin Tools (or another component) and that stops the site from working. One of the configuration options is not compatible with your server. Only trial and error can find out which one. Turn them off one at a time and then slowly turn them back on again. Or alternatively, you can switch half off and reload the page. If it works you know it's one of the bottom half options that is now turned off. Now turn on half of them. Doing it this way and halving each time can be a quicker way to troubleshoot.

Step 8: Missing PHP Modules

Joomla has some core PHP modules and some optional technical requirements.

Here's the link to them: https://docs.joomla.org/J4.x:Optional_Technical_Requirements

Only you will know if you have decided to use cache or other items in those areas.

If you have just changed your PHP version, perhaps you didn't switch on one of these modules but it was on in the previous PHP version.

I can change these modules in my cPanel provided by my host. However, some hosts require you to use php.ini to update these settings. Php.ini is a configuration file for PHP. It's pretty simple, but it looks like jargon if you aren't used to it.

You need to know which setting you are looking for, and then you can search the file to see if anything relevant comes up.

Here is an example of a line that is commented out using a semi-colon. ;

; How many GET/POST/COOKIE input variables may be accepted

;max_input_vars = 1000

If I want max_input_vars to have a value I would remove the semi-colon from the front of the line.

; How many GET/POST/COOKIE input variables may be accepted

max_input_vars = 1000

The first line is just a comment/instruction, so you can leave that commented out, i.e. leave the semi-colon in place.

You could then change the value 1000 to any other number (usually in increase) to see if it worked.

Not all hosts allow access to php.ini and some only allow access to some parts. That is to say, even if you update this value, your host may not allow it. They may either restrict the limit or not allow access to that option at all. Only your host will know.

Step 9: Caching issues?

To be clear this is almost certainly NOT a browser cache issue. An error 500 is a server issue. However, I have in some cases seen it cached in certain components. So you could clear browser cache for a sanity check.

This is very much related to the previous step, but if you have migrated your site from live to dev or dev to live, the chances are your caching settings could have changed.

I, for example, sometimes use Redis.

Browse your files either using FTP or your host's file manager and look for the session handler. Here's what mine looks like:

public $session_handler = 'redis';

Specifically in my instance the error was the redis.sock location had changed.

public $session_redis_server_host = '/home/tpwcsquareballoo/redis.sock';

Make sure this is accurate. You may need to ask your host for that information.

In any case, before trying any of that, you can easily test if this is the issue or not.

Change the line to say:

public $session_handler = ‘file’;

Refresh your page.

If it works, it's probably related to cache. At least you can now troubleshoot that issue.

If it doesn't work, it might be worth leaving cache turned off for now until you resolve the issue, you don't need an extra variable.

But don't forget to turn it back on again in the future once it's working. You can do that in the Joomla Admin:

System > Global Configuration > System > Session Handler (dropdown).

Step 10: Cache Handler?

Open your configuration.php file (using FTP or you host's file manager).

Find this line:

public $cache_handler = 'file';

If the last part doesn't say ‘file' change it to say that.

Refresh your site.

If it works, that's the issue, if not, you can change it back again.

Step 11: What changed?

This is a pretty comprehensive guide, if nothing has worked, it's worth asking what you were just doing before the error. Did you install something on your server? Did you do something else?

Step 12: Ask for help!

At this point you should already have some detailed information. I would recommend you write up all of the information when asking for help. I prefer Stack Exchange but here are your support options:

• https://joomla.stackexchange.com/
  If you use this, when you ask your question be sure to include all of the steps you have taken so far. You have taken a lot of the right steps, include all of the information as to what happened after each step. Did the error message change? Include the full error message.
• https://forum.joomla.org/
• https://joomlacommunity.cloud.mattermost.com/login the official Joomla chat application. Used for Joomla Volunteers to communicate. It's full of experts. I would probably use one of the official support places prior to asking for help here, but it's a good way to get involved in the project and network with knowledable Joomlers.
• Facebook: https://www.facebook.com/groups/joomlanospam this is a lively community with lots of knowledgeable and helpful people.
• User Groups. These are formed by users of Joomla. They are volunteers. They aren't necessarily run by Joomla themselves or by the key people. You can see if there is one near to you: https://community.joomla.org/user-groups.html some are more lively than others. And some DO have the people who write the Joomla code within them.
  • Joomla User Group London: My favourite one is quite lively https://www.joomlalondon.co.uk/
  • Joomla User Group Australia https://community.joomla.org/events/joomla-australia-user-group-1679382001-1715670000.html
  • Joomla User Group Chicago https://community.joomla.org/user-groups/joomla-user-group-chicago-north.html
• Other Joomla Events. These are great places to network and meet experts, members of the core Joomla team and see fantastic presentations on all the things you can do with Joomla. You can find them on the Joomla events page: https://community.joomla.org/events.html
  • All Joomla Days 
  • I can particularly recommend Joomla Day USA if you get a chance to go (even virtually).
  • There have also been Joomla Days in the UK
  • Holland and Germany also have healthy communities with Joomla Days.
• Discord - https://discord.me/joomla another unofficial channel that you might find help in. I believe there are more than one Discord channels.
• Slack – there are a few unofficial Slack user groups too.

And of course

Step 13: Ask an Expert for help

Why waste your time and frustration if you are an end user and not an IT savvy person of a developer. There are tonnes of experts that offer paid help.

Obviously, we are one, so I will recommend my company, Square Balloon, first. We have been working with Joomla for 16 years.

But you can also find more in the service providers directory https://community.joomla.org/service-providers-directory.html