Custom 404 Error Pages for Joomla - The Right Way

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. The idea is to make it a complete webpage, so you can just put HTML straight in there.

That’s it.

Step by Step

Here it is in steps. Replace your-template in /templates/your-template/ with the directory name for your template.

1. If it doesn't exist, copy error.php from /templates/system/ to /templates/your-template/
2. Add the five lines of code shown above to /templates/your-template/error.php
3. Create error-404.php in /templates/your-template/
4. Put the HTML that you want for the 404 error page in error-404.php

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.

Here's an example.

Just that in the middle of a white background.

It's probably more useful to view the example as an actual page - albeit with the links not active and a <meta> noindex tag added.

I set that up today for a site that I operate. The idea is to make it what works for the site that you're configuring.

It makes its point in the first two words, and they can't be missed. That may be all the visitor needs. It then goes on to explain 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

Conclusion

While Joomla doesn't provide a clean way to set up error pages that have access to the same facilities that the main template has, it's perhaps better that it doesn't. A simple page with a completely different design and minimal features can be a useful and clear way to present a 404 error, offering the user useful entry points within the main site to continue their journey.