Plack::...ocument(3)

✨ NAME ✨

Plack::Middleware::ErrorDocument — it's giving "pick your own error page per HTTP status code" 💅

Oh and btw bestie, this is from the User Contributed Perl Documentation manual, page Plack::...ocument(3) — yes the name is literally abbreviated like that, she's mysterious, she's iconic, we love her 🎀

---

🌸 SYNOPSIS 🌸

# in app.psgi
use Plack::Builder;

builder {
    enable "Plack::Middleware::ErrorDocument",
        500 => '/uri/errors/500.html', 404 => '/uri/errors/404.html',
        subrequest => 1;
    $app;
};

---

💖 DESCRIPTION 💖

okay so <pink>Plack::Middleware::ErrorDocument</pink> lets you customize your error screen, no cap — you just hand it paths (either a file system path OR a URI path, dealer's choice 🦋) for error pages, matched up per status code. Obsessed.

---

🧚 CONFIGURATIONS 🧚

🌈 subrequest

A boolean flag, bestie — it says whether to serve error pages using a brand new GET sub request. Defaults to false, which means it serves error pages using the file system path instead. 🙈

builder {
    enable "Plack::Middleware::ErrorDocument",
        502 => '/home/www/htdocs/errors/maint.html';
    enable "Plack::Middleware::ErrorDocument",
        404 => '/static/404.html', 403 => '/static/403.html', subrequest => 1;
    $app;
};

So this config serves 502 error pages straight from the file system, assuming that's when you're probably maintaining a database and stuff (it's giving maintenance era 💀), BUT it serves the 404 and 403 pages using a sub request so your application can do some logic in there — like logging, or dropping suggestions. Main character behaviour fr fr.

⭐ Ngl, super important: when you're using a subrequest, the subrequest should return a regular '200' response. Periodt.

---

👑 AUTHOR 👑

Tatsuhiko Miyagawa — the icon, the legend 💜

---

🔥 SEE ALSO 🔥

gonna be honest bestie, there's nothing else listed here 😭 it's just this page, and she ate.

---

slay, that's the whole page ✨ This was pulled from perl v5.42.3 on 2026-10-18 — mwah 💅💖