Redirects & 404s

When a URL on your site returns 404, it’s usually one of these: the content isn’t published (or isn’t published yet), the URL mode or language routing changed, a redirect can’t do its job, or the request was for something on purpose excluded from your static output. This page walks through each, and when to fix it in the admin versus the server config.

Content isn’t built until it’s due

Only published, non-deleted content is generated. If a page schedules publishing in the future, or an unpublish date has already passed, the page is simply not built, so its URL is a 404 until the next build after it becomes eligible. After changing published status or a schedule window, rebuild.

Language routing mismatches

URL behavior depends on the Language URL Mode (Settings → Permalinks), which is also where a common class of 404s starts:

• If you configure none (no language segments) but more than one language, the builder overrides it to path mode and warns in the build log. If you’re seeing unexpected /en/…-style paths, check this setting.
• In subdomain mode, URLs are language subdomains (like es.yourdomain.com), but files are still built into output/{lang}/ directories. Your server must route each subdomain to its language directory; forgetting that makes the subdomain 404 or serve the wrong language.
• A stale URL mode on a monolingual site (for example path mode when only one language exists) produces 404s for the default paths. Clear the mode (or set the correct mode) and rebuild.

The builder prints warnings and notes about these exact situations in the build output, so open the build log first when language URLs are behaving oddly.

The root URL redirects to a wrong page

Where the domain root points is set by home_redirect (Settings → Permalinks). If the slug you name isn’t a published page, the build log warns “no published page with this slug found.”, and the root redirect stops working correctly. Fix the setting or publish/restore the target page, then rebuild.

Redirects that silently don’t apply

Redirects apply only to old paths that don’t already contain published content. If a page or post still lives at the old slug, it keeps 200-serving that URL and the redirect is skipped; the build log will still mark this by the “old slug is still active” warning the admin shows when creating such a redirect. To make a redirect win, unpublish or delete the old page first (or keep the redirect and unpublished content by toggling the publish state).

Redirects need to be active (the active checkbox in the redirects screen). Only active redirects generate redirect output at build time; a deactivated redirect is gone from the static output until you activate it (activate triggers a build).

Restrictive formats win: simple redirects use the 301/302/307 code you chose and are applied in the generated server redirect config; pattern redirects (old slug ending in * with $1 substitution in the destination) work only as HTML redirect pages in the static build, and are skipped by the generated server configs.

When a 404 itself is broken

The static site ships a built 404 page. If that page fails to render in a build, the build log records an error line for it but continues; the site stays up, while a missing custom 404 leaves your server’s plain “Page not found” response in charge until the next good build.

Probes aren’t served the regular 404

The stock server config routes common attack-probe paths (settings files, version-control paths, admin URLs of other platforms) through a proxy that has nothing to do with your static output, instead of serving your normal 404 page. If you see 404s logged for those exact paths, they’re probes, not broken links.

Why a 404 can briefly flash during deploys

Publish swaps output atomically. When the live content location is a symlink, going live is a single atomic rename, zero downtime. Otherwise it’s a two-step rename on the same filesystem, with a brief gap between the two renames during which a request could hit a missing directory. Either way a swap either fully lands or the previous output stays in place, never a partially-written site.

Where to go next

Once you know a URL should exist but 404s, unpublish or delete the old page, publish the new one, and create a redirect from the logged path using the 404 monitor’s per-row Create redirect link or the bulk selection (Admin → Health → 404s tab). The 404 log records missing paths with hit counts and referring URLs so you can prioritize the fixes.