The Right Way to Create a Custom 404 Error for Joomla

No matter how careful you are to ensure that there are no broken links on a website, there are still going to be times when a “404 Not Found” error is going to crop up. It may be an old page that no longer exists and which hasn’t been assigned a “410 gone” status. It may indeed be a broken link. It may be a broken link from another website. A visitor may type in an address that doesn’t exist. Something may go wrong with the website.

When it happens, it’s essential to provide a smooth experience for the visitor. This can be even more important if the visitor is a potential customer. A negative experience may lead to them moving on with no intention of returning.

When the website is running on the Joomla platform, this is not as simple as it perhaps could be. In this article I’ll aim to outline an approach to creating a custom 404 error page for Joomla that doesn’t have the issues found in some common solutions to this. I’ll also describe what those common solutions are and why they’re not ideal.

The Short Version

Here’s the idea in a nutshell.

If you don’t already have an override for the error.php file, you’ll need to create one. To do that, copy /templates/system/error.php to the root of your template.

Next, add the following to the top of that file, just after the line defined('_JEXEC') or die;.

if ($this->error->getCode() === 404) {
    http_response_code(404);
    include __DIR__ . '/error-404.php';
    exit;
}

What this tells Joomla is to use the contents of error-404.php when it’s displaying a 404 error, and not to continue processing the rest of the error.php file.

Now, you can set up error-404.php in whatever way you want your 404 error page to appear.

That’s it.

But...

Ok, so perhaps you’re wondering how that helps. You may feel that you’re in the same situation that you were before starting here. Did you want to set up your 404 page so that it uses the same template as the rest of your website? I get that. And Joomla doesn’t provide any easy way to do it, but what I’m suggesting is that you don’t need to do that. Here’s why.

Keep your 404 page simple. Give it its own design and keep it absolutely minimal. That way, when the page loads, the user will immediately be clear that this is not like the rest of the site. They won’t go through an initial feeling that they have landed on the page that they expected, only to then be disappointed when they start to give it their attention, and find that in fact it’s an error page. That will be clear from the start.

Then, because you keep the page design as simple as it can be, they’ll be very easily able to pick up the fact that the page wasn’t found, and decide what to do. Your job at that point may well be done.

For visitors that don’t already know what they want to do about it, or are unsure, provide a few suggestions about what they might do next on the website, along with some reassurance about what happened, in case they’re confused.

And that’s all you need to do.

Commonly Found Solutions

There are a couple of solutions out there that are commonly found. Let’s take a look.

Redirect to a Custom Page

This idea is that you create a custom page and then use an instruction like:

header("Location: /custom-page-alias")

This creates a 302 redirect to your custom page.

The problem with this is that instead of sending a 404 error, the user will actually receive a 302 redirect and then land on a different page. In http speak, this means that the page has moved to a new location, not that it doesn’t exist. This issue is particularly harmful for search engines visiting the site, but can also be confusing for people.

Load the Content of a Custom Page

The idea here starts off the same, that you create a custom page with your 404 error, but instead of redirecting to it, you fetch the contents of it using file_get_contents(), something like this:

echo file_get_contents(JURI::root()."custom-404-error-page");

And then send that as the contents of your 404 error page.

This isn’t so bad, since a 404 http response code will be sent, but it’s still messy. It creates a second request to the server, when creating the response could all be done within the existing request. It also creates a page which could be loaded directly and say that it’s a not found page when it’s actually providing a 200 response code.

It’s not a clean solution, but if you do really want to use the same template as the rest of your site, then it’s the best you can do at present. This is because Joomla doesn’t provide a way to get access to the site content once the request has been directed to the error page. Sad, but true. And it doesn’t look like they have any intention of resolving it.

Back to the Point

So as I was saying. The idea I’m proposing is to set up an “error-404.php” file in your template, and make that a completely custom page with its own design, its own CSS, and if you really need them, its own images. But to keep it extremely simple. Don’t make it look like the site in any way at all. Don’t brand it. Make it an error page, that can be quickly consumed before moving on to something that is working.

A page that looks like the rest of the site sends a confusing message. It’s working but not working. A plain page with no frills and a clear message, that still looks appealing in its own way, although very simple, sends a clear message.

This isn’t what you were expecting. Here’s why in a few words. Here’s what you can do now.

I did this today for a site that I operate. This is an example. Make it what works for you.

Just that in the middle of a white background.

It makes its point in two words. That may be all the visitor needs. It explains the situation. It offers a contact option if it’s a big issue for the visitor. It explains a little more in case they are needing reassurance and to explain that these types of errors are reported automatically. It offers useful ways to continue browsing the site and find what they’re looking for. Importantly, it reinforces the main point of this particular website, which is to encourage visitors to contact the team with their needs.

More could be done, but that’s what the rest of the website is already for. Point the user in the direction of whatever the site offers that is likely to be useful to them, without trying to do too much. Three or four links at most. And stop. Keep it simple.

The title of the page is just as simple:

Not Found - 404 Error