Custom 404 & MaintenanceDocs

Custom 404 & Maintenance Documentation

Installation steps and a complete reference for every setting, with concrete examples — the same level of detail our support uses to help customers.

View as Markdown

Before and after

Same store, same URL: drag the handle to compare the standard Magento page with the page generated by the module.

404 page

Custom 404 page with the store logo, large 404 number, “Page not found” title, search box and button back to the home page Standard 404 page of the Hyvä theme with header, footer and the generic text “Whoops, our bad...”
Standard Magento With the module

Left: the theme’s standard 404 page (here Hyvä), with header, footer and generic text. Right: the same URL with the module — full screen, store logo, large 404, catalog search and a button back to the home page.

Maintenance page

Branded maintenance page with the store logo, the title “We’ll be back soon” and the note “We will be back online at 14:00 (CET)” Standard Magento maintenance page: “Service Temporarily Unavailable” in black text on a white background
Standard Magento With the module

Left: Magento’s standard maintenance page, “Service Temporarily Unavailable” in black on white. Right: the branded page with logo, message and the highlighted note “We will be back online at 14:00 (CET)”, served with HTTP 503.

Installation

Requirements

Magento 2.4.x. PHP 8.1–8.5. Compatible with both the default Luma theme and the Hyvä theme. Depends on the free codingrow/module-core module, installed automatically. No key to enter: the module activates automatically on your domain.

Setup steps

  1. Request the module on the product page with just your email: you receive the Composer credentials by email (they are also in your customer area). Save them from your Magento project root: 
    composer config http-basic.repo.codingrow.com <username> <password>
  2. composer config repositories.codingrow composer https://repo.codingrow.com
  3. composer require codingrow/module-custom-404-maintenance
  4. bin/magento module:enable Codingrow_Custom404Maintenance
  5. bin/magento setup:upgrade — in production mode also setup:di:compile, setup:static-content:deploy and cache:flush.
  6. There is no key to paste: the module activates automatically on your domain, so go straight to the configuration below.

setup:upgrade also installs the maintenance page skin in pub/errors. If it could not (file permissions), run bin/magento codingrow:c404m:deploy once as the Magento file owner.

Configuration

Open Admin → Stores → Configuration → Codingrow Extensions → Custom 404 & Maintenance. Every field can be set at Default, Website and Store View level: use the Scope switcher at the top left to set different texts or design per language.

The module header at the top of the configuration page, with the installed version.
The module header at the top of the configuration page, with the installed version.
License group: status Active and an empty License Key field — the module is free, no key is needed.
License group: status Active and an empty License Key field — the module is free, no key is needed.
SettingWhat it doesNotes
404 Page
Enable custom 404 pageReplaces the Magento 404 page.Yes/No.
Show large "404" numberBig colored number above the title.Uses the accent color.
Title / MessageThe texts of the page.Empty = translated default text. Basic HTML allowed in the message (b, strong, i, em, a, br, p, ul, ol, li, span).
Show search boxCatalog search of the store.—
"Back to home" button labelText of the button.Empty = default text.
Maintenance Page
Installation statusWhether the skin is installed in pub/errors.Must say Installed (see Maintenance page).
Enable custom maintenance pageShows your page while maintenance mode is on.Yes/No per store view.
Title / MessageThe texts of the page.As for the 404 page.
Highlighted noteShort note in the accent color.E.g. "Back online at 2 PM".
Auto-reload page every (seconds)Reloads the visitor's page automatically.0 = never; 60 = every minute.
Design
Logo / Logo max widthStore logo, custom logo or none.Store logo = the one set in Content → Design → Configuration.
BackgroundSolid color, two-color gradient or full-screen image.Image darkening from 0 to 90%.
Content boxNone, light or dark.—
Font / Title size / AlignmentTypography of both pages.—
Text, accent and button text colorsColors, each with a color picker.Accent = 404 number, links, buttons, note.

Uninstallation

Restore the standard Magento maintenance page before removing the module:

bin/magento codingrow:c404m:deploy --uninstall
composer remove codingrow/module-custom-404-maintenance
bin/magento setup:upgrade

If you remove the module without --uninstall, the maintenance page keeps showing the last generated version until the skin is removed. To simply go back to the standard pages without uninstalling, set Enable custom 404 page and/or Enable custom maintenance page to No.

User guide

404 page

When a URL does not exist, instead of the CMS “404 Not Found” page the store shows a full-screen page with the logo, an optional large “404”, title, message, an optional search box and a “Back to home” button. The response keeps the HTTP 404 status, carries noindex and is never cached, so search engines do not index it.

Static files are not affected. 404s for missing images, CSS or JS files are handled by the web server, not by Magento, so they keep the server's own response.
The 404 Page (Not Found) group: enable, large “404” number, title, message, search box and “Back to home” button label. Empty fields use the translated default texts.
The 404 Page (Not Found) group: enable, large “404” number, title, message, search box and “Back to home” button label. Empty fields use the translated default texts.
The resulting 404 page on desktop: logo, 404, title, message, search box and button back to the home page.
The resulting 404 page on desktop: logo, 404, title, message, search box and button back to the home page.
The same 404 page on a smartphone.
The same 404 page on a smartphone.

Maintenance page

While maintenance mode is on (bin/magento maintenance:enable) Magento is not running and pub/errors/503.php answers instead. The module therefore:

  1. installs a skin in pub/errors/codingrow_c404m/ and activates it in pub/errors/local.xml (an existing local.xml is backed up to local.xml.codingrow_c404m.bak);
  2. pre-generates the page HTML for every store view;
  3. during maintenance picks the store view of the request (web server MAGE_RUN_CODE → domain/path → store cookie → browser language → default store) and serves its page with HTTP 503 and Retry-After. If the page is not enabled for that store view, the standard Magento page is shown.

The HTML is regenerated automatically when you save the section, when the logo changes in Content → Design → Configuration and on every maintenance:enable. IPs excluded with --ip keep seeing the store.

Installation status says “Not installed yet”? The web server cannot write to pub/errors (normal and safe on hardened servers). Run bin/magento codingrow:c404m:deploy once as the Magento file owner, then reload the configuration page: it must say Installed.
The Maintenance Page group: Installation status Installed with the date the page was last generated, enable, title, message, highlighted note and auto-reload.
The Maintenance Page group: Installation status Installed with the date the page was last generated, enable, title, message, highlighted note and auto-reload.
The maintenance page during bin/magento maintenance:enable, with the highlighted note “We will be back online at 14:00 (CET)”.
The maintenance page during bin/magento maintenance:enable, with the highlighted note “We will be back online at 14:00 (CET)”.
The same maintenance page on a smartphone.
The same maintenance page on a smartphone.

Design

The design applies to both pages: logo (store logo, custom logo — jpg, png, gif, svg, webp — or none) with a maximum width; background as solid color, two-color gradient or full-screen image with 0–90% darkening; content box none, light or dark; font, title size and alignment; text color, accent color (404 number, links, buttons, note) and button text color, each with a color picker. The page is self-contained HTML/CSS and does not use the theme, so it looks identical on Hyvä and Luma.

The Design (both pages) group with a gradient background: logo and logo max width, background and gradient colors, content box, font, title size, alignment, text, accent and button text colors.
The Design (both pages) group with a gradient background: logo and logo max width, background and gradient colors, content box, font, title size, alignment, text, accent and button text colors.
Background set to Image: thumbnail of the uploaded image, the Delete Image option and Image darkening (%), here 15.
Background set to Image: thumbnail of the uploaded image, the Delete Image option and Image darkening (%), here 15.
Result with the background image, 15% darkening, light content box and a blue accent color.
Result with the background image, 15% darkening, light content box and a blue accent color.
Another combination: no content box, serif font, left alignment and a terracotta accent color.
Another combination: no content box, serif font, left alignment and a terracotta accent color.

Live preview

The Live Preview group shows the 404 page or the Maintenance page, on Desktop or Mobile, updated while you edit the fields and using the selected scope — before you save. Newly uploaded images (custom logo, background image) appear in the preview after saving.

Live preview with unsaved changes: dark background, purple accent and the custom title “Oops! This page took a day off”.
Live preview with unsaved changes: dark background, purple accent and the custom title “Oops! This page took a day off”.
The 404 page / Maintenance page and Desktop / Mobile tabs: here the 404 page on Desktop.
The 404 page / Maintenance page and Desktop / Mobile tabs: here the 404 page on Desktop.
The maintenance page in the Mobile tab.
The maintenance page in the Mobile tab.
After saving, the uploaded background image appears in the preview too.
After saving, the uploaded background image appears in the preview too.
Preview of the maintenance page with the same background image.
Preview of the maintenance page with the same background image.

CLI command

bin/magento codingrow:c404m:deploy installs or updates the maintenance skin in pub/errors and regenerates the pages for all store views. You only need it when pub/errors is not writable by the web server; the skin files are created with 644/755 permissions. --uninstall restores local.xml and removes the skin, bringing back the standard Magento maintenance page.

codingrow:c404m:deploy regenerates the page for the store views; after maintenance:enable visitors see the branded page (HTTP 503); --uninstall restores the standard Magento page before you remove the module.
codingrow:c404m:deploy regenerates the page for the store views; after maintenance:enable visitors see the branded page (HTTP 503); --uninstall restores the standard Magento page before you remove the module.

Troubleshooting

  • I still see the old 404 page: check that Enable custom 404 page is Yes in the scope of the store view you are looking at, flush the cache (System → Cache Management) and test a URL that really does not exist.
  • During maintenance I see the standard Magento page: Installation status must be Installed, the page must be enabled for that store view and your IP must not be excluded with --ip. Then run bin/magento codingrow:c404m:deploy.
  • Wrong language during maintenance: set the texts in the scope of the right store view; if several store views share the same address, the store cookie and then the browser language decide. Run bin/magento codingrow:c404m:deploy afterwards.
  • The logo does not show: with Store logo it comes from Content → Design → Configuration → Header → Logo Image (or the theme's logo); choose Custom logo to upload one, and increase Logo max width if it looks too small.
  • The background image is missing from the preview: uploaded images appear after saving; make sure Background is set to Image.

License

Custom 404 & Maintenance is free and there is no key to enter: once installed, the module activates automatically on your domain. It makes a light online check with codingrow.com, sending only the store domain, the product and the installed version (no data about your customers), and remembers the last answer, so a temporary network problem does not switch it off. The form on the product page only sends you the credentials for the Codingrow Composer repository, which you use to download the module and its updates.

If the module ever becomes paid: domains that have already activated it stay free, forever, on all versions released up to that date — no domain change and no support request needed. The Magento log states the last version you can install for free; newer versions would require a license.