How can I make custom 404 pages?

Overview

Upsun’s infrastructure acts as a transparent conduit for your web traffic. When a user requests a URL that doesn’t exist, the Upsun router doesn't know whether that path is "wrong" or just handled dynamically by your code.

Consequently, custom 404 pages must be handled at the application level. This guide explains how to implement these pages across different programming environments.

1. The Core Principle: Application Responsibility

In a standard Upsun environment, your .upsun/config.yaml usually defines a passthru. This tells the web server: "If you don't find a physical file matching this request, give the request to the application."

Because the application receives the request, it is the application's job to:

1. Check its internal routing table.

2. Determine that no route matches.

3. Return a 404 Not Found HTTP status code.

4. Render the custom HTML for the user.

2. Implementation Examples

JavaScript (Node.js/Express)

In Express, you handle 404s by adding a middleware function at the very end of your route definitions. This "catch-all" ensures that if no previous route matches, the 404 logic triggers.

const express = require('express');
const app = express();

// ... your standard routes (app.get('/home', ...))

// The 404 Catch-all (must be the LAST route)
app.use((req, res, next) => {
  res.status(404).send("<h1>404: Page Not Found</h1>");
  // Or render a template: res.status(404).render('404');
});

Python (Flask)

Flask provides a specific decorator to handle standard HTTP errors gracefully.

from flask import Flask, render_template

app = Flask(__name__)

@app.errorhandler(404)
def page_not_found(e):
    # Note that we set the 404 status explicitly
    return render_template('404.html'), 404

PHP (Native)

If you aren't using a framework like Symfony or Laravel, you must manually set the response header before sending any output.

<?php
// Your routing logic here...

if ($route_not_found) {
    http_response_code(404);
    include('errors/404.php');
    exit;
}

3. Why it must be handled this way

Handling errors within the application rather than at the infrastructure level provides several benefits:

• Contextual Awareness: Your app knows if a user is logged in and can provide a personalized 404 page (e.g., "Hey John, we couldn't find that page, but here are some links you might like").

• Unified Branding: Your error pages can use the same templates and CSS as the rest of your site without duplicating files.

• Proper SEO: By handling the error in code, you ensure a true 404 status header is sent, preventing search engines from indexing broken links.

4. Common Pitfalls

• Absolute Paths: On a 404 page, the URL depth can vary (e.g., /broken vs /blog/broken). Use absolute paths (starting with /) for your images and CSS to ensure they load correctly.

• Avoid Redirects: Never "redirect" (301/302) a user to a /404 URL. This is bad for SEO. Instead, keep the user on the URL they typed and simply return the 404 status and content.

• Status Codes: Always verify that your application is actually sending the 404 status code. You can check this in your browser's "Network" tab in Developer Tools.