# 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.

Custom 404 & Maintenance is a **free** Magento 2 module with **no key to enter** (it activates automatically on your domain): it replaces the Magento 404 page and the maintenance page with full-screen, branded pages (store logo, texts per store view, background, colors, fonts) with a live preview in the admin.

## Before and after

![Before: the standard 404 page of the Hyvä theme, with header, footer and the generic text “Whoops, our bad...”](img/404-before.jpg)

![After: the same URL with the module — full-screen page with the store logo, large 404, “Page not found”, search box and “Back to home” button](img/404-after.jpg)

![Before: the standard Magento maintenance page, “Service Temporarily Unavailable” in black text on white](img/maintenance-before.jpg)

![After: the branded maintenance page with the store logo, “We'll be back soon” and the highlighted note “We will be back online at 14:00 (CET)”](img/maintenance-after.jpg)

## 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 (free) on https://codingrow.com/custom-404-maintenance/ with just your email (no domain needed). You receive by email your personal credentials for the Codingrow Composer repository (the same credentials work for every Codingrow module and are also shown in your customer area at https://codingrow.com/account). 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 `bin/magento setup:di:compile`, `bin/magento setup:static-content:deploy` and `bin/magento cache:flush`.
6. There is no key to paste: the module activates automatically on your domain, so go straight to the configuration.

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

```
bin/magento codingrow:c404m:deploy
```

### Configuration

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

![Module header at the top of the configuration page: “Custom 404 & Maintenance 1.0.1 by codingrow.com”, showing the installed version](img/admin-header.jpg)

![License group: License status “Active” and an empty License Key field, with the note that the module is free and no key is needed](img/admin-license.jpg)

#### 404 Page

| Setting | What it does | Notes |
|---|---|---|
| **Enable custom 404 page** | Replaces the Magento 404 page. | Yes/No. |
| **Show large "404" number** | Big colored number above the title. | Uses the accent color. |
| **Title** / **Message** | The texts of the page. | Empty = default text, already translated (EN, IT, DE, FR, ES, NL, PT). Basic HTML allowed in the message (b, strong, i, em, a, br, p, ul, ol, li, span). |
| **Show search box** | Catalog search of the store. | — |
| **"Back to home" button label** | Text of the button. | Empty = default text. |

![404 Page (Not Found) group: Enable custom 404 page, Show large “404” number, Title, Message, Show search box and “Back to home” button label](img/admin-404.jpg)

#### Maintenance Page

| Setting | What it does | Notes |
|---|---|---|
| **Installation status** | Whether the skin is installed in `pub/errors`. | Must say **Installed** (see "Maintenance page" below). |
| **Enable custom maintenance page** | Shows your page while maintenance mode is on. | Yes/No per store view. |
| **Title** / **Message** | The texts of the page. | As for the 404 page. |
| **Highlighted note** | Short 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. |

![Maintenance Page group: Installation status “Installed” with the date the page was last generated, Enable custom maintenance page, Title, Message, Highlighted note and Auto-reload page every (seconds)](img/admin-maintenance.jpg)

#### Design (both pages)

| Setting | What it does | Notes |
|---|---|---|
| **Logo** / **Logo max width** | Store logo, custom logo (jpg, png, gif, svg, webp) or none. | Store logo = the one set in Content → Design → Configuration (or the theme logo). |
| **Background** | Solid color, two-color gradient or full-screen image. | Image darkening 0–90%. |
| **Content box** | None, light or dark. | — |
| **Font** / **Title size** / **Alignment** | Typography of both pages. | — |
| **Text**, **accent** and **button text** colors | Colors, each with a color picker. | Accent = 404 number, links, buttons, note. |

![Design (both pages) group with a gradient background: logo, logo max width, background and gradient colors, content box, font, title size, alignment, text, accent and button text colors with color pickers](img/admin-design.jpg)

![Design group with Background set to Image: thumbnail of the uploaded image, Delete Image checkbox and Image darkening (%) set to 15](img/admin-design-image.jpg)

#### Live Preview

Tabs *404 page* / *Maintenance page* and *Desktop* / *Mobile*, updated while you edit the fields, using the selected scope — before you save. Newly uploaded images appear in the preview after saving.

![Live preview with unsaved changes: dark background, purple accent color and the custom title “Oops! This page took a day off”](img/preview-unsaved-edit.jpg)

### 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 the module is removed without `--uninstall`, the maintenance page keeps showing the last generated version until the skin is removed. To simply go back to the standard pages, 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. 404s for missing static files (images, CSS, JS) are handled by the web server, not by Magento, so they are not affected.

![The custom 404 page on a smartphone: logo, 404, title, message, full-width search box and “Back to home” button](img/404-mobile.jpg)

### Maintenance page

While maintenance mode is on (`bin/magento maintenance:enable`) Magento is not running and `pub/errors/503.php` answers. 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 the section is saved, when the logo changes in Content → Design → Configuration and on every `bin/magento maintenance:enable`. IPs excluded with `--ip` keep seeing the store.

If **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.

![The maintenance page on a smartphone, with the highlighted note “We will be back online at 14:00 (CET)”](img/maintenance-mobile.jpg)

### Design

The page is self-contained HTML/CSS and does not use the store theme, so it looks identical on Hyvä and Luma.

![Background image with 15% darkening, light content box and blue accent color on the 404 number and buttons](img/404-variant-image.jpg)

![The same background image variant on a smartphone](img/404-variant-image-mobile.jpg)

![Minimal variant: no content box, serif font, left alignment and terracotta accent color](img/404-variant-minimal.jpg)

### Live preview

The preview sits right below the settings: choose *404 page* or *Maintenance page*, then *Desktop* or *Mobile*.

![Live preview: 404 page tab, Desktop](img/preview-404-desktop.jpg)

![Live preview: Maintenance page tab, Mobile](img/preview-maintenance-mobile.jpg)

![Live preview of the 404 page after saving an uploaded background image](img/preview-404-image.jpg)

![Live preview of the maintenance page with the same uploaded background image](img/preview-maintenance-image.jpg)

### CLI command

`bin/magento codingrow:c404m:deploy` installs or updates the maintenance skin in `pub/errors` and regenerates the pages for all store views (skin files created with 644/755 permissions). Needed only when `pub/errors` is not writable by the web server. `--uninstall` restores `local.xml` and removes the skin.

![Terminal: codingrow:c404m:deploy (page generated for the store views), maintenance:enable (visitors see the branded page, HTTP 503), maintenance:disable, and codingrow:c404m:deploy --uninstall to restore the standard page before removing the module](img/cli.jpg)

### Troubleshooting

- **Still the old 404 page:** check **Enable custom 404 page = Yes** in the scope of the store view you are viewing, flush the cache (System → Cache Management), test a URL that really does not exist.
- **Standard Magento page during maintenance:** **Installation status** must be **Installed**, the page must be enabled for that store view, 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.
- **Logo not showing:** with **Store logo** it comes from Content → Design → Configuration → Header → Logo Image (or the theme logo); choose **Custom logo** to upload one; increase **Logo max width** if too small.
- **Background image missing from the preview:** uploaded images appear after saving; make sure **Background** is set to **Image**.

### License

Free, with 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 asks only for your email and sends the credentials for the Codingrow Composer repository (download and 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.

## Changelog

- **v1.0.1** (2026-09-16) — Fixed an error that prevented the configuration page from opening after the license status was introduced.
- **v1.0.0** (2026-09-16) — First release.