Custom Error Page #

Halaman error bawaan Nginx sangat minimalis — hanya teks putih di layar dengan kode status dan tulisan “nginx”. Untuk website production, kamu hampir pasti ingin menggantinya dengan halaman yang lebih sesuai tampilan site, memberikan informasi yang berguna, atau setidaknya tidak mengekspos versi Nginx yang digunakan.

Directive error_page #

error_page mendefinisikan apa yang ditampilkan untuk kode status HTTP tertentu:

server {
    root /var/www/html;

    # Satu kode status → satu file
    error_page 404 /404.html;

    # Beberapa kode status → satu file
    error_page 500 502 503 504 /50x.html;

    # Pastikan file error bisa diakses
    location = /404.html {
        internal;   # Hanya bisa diakses internal, tidak dari browser langsung
    }

    location = /50x.html {
        internal;
    }
}

Directive internal mencegah pengguna mengakses /404.html secara langsung melalui browser — file itu hanya ditampilkan oleh Nginx sebagai respons error.

Menyimpan File Error di Lokasi Terpisah #

Kadang lebih rapi menyimpan semua halaman error di satu direktori:

server {
    root /var/www/html;

    error_page 400 /errors/400.html;
    error_page 401 /errors/401.html;
    error_page 403 /errors/403.html;
    error_page 404 /errors/404.html;
    error_page 500 502 503 504 /errors/50x.html;

    # Satu location yang menangani semua file error
    location ^~ /errors/ {
        root /var/www;   # File ada di /var/www/errors/
        internal;
    }
}

Mengubah Kode Status Respons #

Secara default, error_page melakukan redirect internal dan tetap menggunakan kode status asli. Kamu bisa mengubah kode status yang dikembalikan ke browser:

# Tampilkan 404.html tapi tetap return status 404 (default)
error_page 404 /404.html;

# Tampilkan halaman 404 tapi return status 200
# (berguna untuk beberapa framework SPA)
error_page 404 =200 /index.html;

# Tampilkan halaman error tapi ubah ke kode lain
error_page 403 =404 /404.html;
# (menyembunyikan keberadaan resource yang terlarang)

Error dari Upstream / Backend #

Ketika Nginx digunakan sebagai reverse proxy, error bisa datang dari backend. error_page bisa menangani ini juga:

server {
    location / {
        proxy_pass http://backend;

        # Intercept error dari backend dan tampilkan halaman kustom
        proxy_intercept_errors on;

        error_page 502 503 504 /maintenance.html;
    }

    location = /maintenance.html {
        root /var/www/html;
        internal;
    }
}

Tanpa proxy_intercept_errors on, halaman error yang dikirim backend akan diteruskan langsung ke browser. Dengan directive ini, Nginx mengambil alih dan menampilkan halaman kustom.

Redirect ke URL Eksternal #

error_page juga bisa redirect ke URL lain, tapi ini akan mengubah kode status menjadi 302 (redirect):

# Redirect ke halaman eksternal saat error
error_page 404 https://example.com/not-found;

# Atau ke path relatif dengan redirect eksplisit
error_page 503 @maintenance;

location @maintenance {
    return 503 "We'll be back soon";
    add_header Content-Type text/plain;
}

Menyembunyikan Versi Nginx di Halaman Error #

Secara default halaman error Nginx mencantumkan versi. Sembunyikan ini:

http {
    # Sembunyikan versi Nginx dari halaman error dan header Server
    server_tokens off;
}

Setelah server_tokens off, header Server hanya menampilkan “nginx” tanpa nomor versi, dan halaman error bawaan pun tidak menampilkan versi.

Contoh Halaman 404 Sederhana #

<!-- /var/www/html/errors/404.html -->
<!DOCTYPE html>
<html lang="id">
<head>
    <meta charset="UTF-8">
    <title>Halaman Tidak Ditemukan</title>
    <style>
        body { font-family: sans-serif; text-align: center; padding: 60px; }
        h1 { font-size: 72px; margin: 0; color: #e74c3c; }
        p { color: #666; }
        a { color: #3498db; }
    </style>
</head>
<body>
    <h1>404</h1>
    <p>Halaman yang kamu cari tidak ditemukan.</p>
    <p><a href="/">Kembali ke halaman utama</a></p>
</body>
</html>

Ringkasan #

error_page 404 /404.html — directive dasar untuk menentukan halaman error kustom per kode status.
Gunakan internal di location error page agar file tidak bisa diakses langsung dari browser.
proxy_intercept_errors on diperlukan agar Nginx menampilkan halaman error kustom saat backend mengembalikan error, bukan halaman error dari backend.
server_tokens off di http context untuk menyembunyikan versi Nginx dari header dan halaman error bawaan.
error_page 404 =200 /index.html berguna untuk SPA yang butuh semua path mengembalikan index.html dengan status 200.

← Sebelumnya: Index & Autoindex Berikutnya: Konsep Reverse Proxy →