Custom 500 Server Error Page Template in Django

When building a web application, it’s important to provide a seamless and user-friendly experience even when things go wrong. One common issue that users might encounter is the “500 Internal Server Error.” While this error can be caused by a variety of server-side issues, you can still make the error experience more pleasant by creating a custom 500 error template. In this tutorial, we’ll walk you through the steps to implement a custom 500 error template in your Django project.

Why Create a Custom 500 Error Template?

The “500 Internal Server Error” is a generic error message that indicates a problem on the server’s end. Instead of showing users a technical error page, you can use a custom template to provide a friendlier message and reassure users that the issue is being looked into. A custom 500 error page can maintain your website’s branding, offer helpful information, and keep users engaged even in error scenarios.

Let’s dive into the process of creating and implementing a custom 500 error template in your Django project.

Step 1: Creating the Custom 500 Error Template

In your Django project, navigate to the templates directory within your app’s main directory.
Create a new subdirectory named 500 (matching the HTTP error code) inside the templates directory.
Inside the 500 directory, create a file named 500.html. This file will contain the content of your custom 500 error page.

Step 2: Creating the Custom 500 Template

In your Django project, navigate to the templates directory. If it doesn’t exist, create it within your app’s main directory.
Inside the templates directory, create a file named 500.html. This file will contain the content of your custom 500 error page.

Step 3: Designing Your Custom 500 Error Page

Design your custom 500 error page just like you would for any other web page. You can use HTML, CSS, and even JavaScript to create an appealing and informative error page. Here’s an example of what your 500.html file might look like:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>500 Internal Server Error</title>
    <style>
        /* Your custom CSS styles go here */
        body {
            font-family: Arial, sans-serif;
            background-color: #f3f3f3;
        }
        .container {
            text-align: center;
            padding: 100px;
        }
        h1 {
            font-size: 48px;
            color: #ff5733;
        }
        p {
            font-size: 18px;
            color: #555;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>Oops! Something Went Wrong</h1>
        <p>We're experiencing technical difficulties. Please try again later.</p>
        <p>If the issue persists, you can contact our support team at [email protected].</p>
    </div>
</body>
</html>

Step 4: Custom 500 View for Django handler500

Create a new view in one of your app’s views files. For example, if your app is named yourapp, you can create a view function in views.py:

from django.shortcuts import render

def custom_500(request):
    return render(request, '500.html', status=500)

Replace 'yourapp' with the actual name of your app.

Step 5: Updating Django Settings

To make Django use your custom 500 error page, you need to update the handler500 view in your project’s urls.py file.

Open your project’s urls.py file.
Add the following line to your URL patterns, before the urlpatterns list:

from django.conf.urls import handler500

handler500 = 'yourapp.views.custom_500'

NOTE: If your project is running in DEBUG mode, then you will not see the page, you need to update Debug Mode and ALLOWED_HOST in settings.py file, like bellow:

DEBUG = False

ALLOWED_HOSTS = ['*']

Step 6: Testing Your Custom 500 Error Page

To test your custom 500 error page:

Start your Django development server.
Simulate a server error (e.g., by intentionally causing an exception in your code). Example:
def hello_world(request): raise Exception('This is a test error')
Instead of the default technical error page, you should now see your custom 500 error page, providing users with a more user-friendly experience.

Conclusion

By creating and implementing a custom 500 error template in your Django project, you can ensure that users are greeted with a friendly and informative message even when encountering server errors. This simple effort can contribute to a better overall user experience and help maintain engagement with your website. Follow the steps in this guide to create a seamless error experience that aligns with your website’s design and branding.

Find this tutorial on Github.