> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/run-in-production/tutorials/create-a-custom-maintenance-page.md).

# Create a Custom Maintenance Page

Learn how to make your site visitors aware of any ongoing maintenance on the project.

A maintenance page will be shown when an Umbraco project is running an upgrade. This prevents visitors from landing on an upgrade page or seeing content meant for project maintainers.

![The default maintenance page making site visitors aware of the state of the site.](https://1282852327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbFfxUcTsPCzuMkpCkZsT%2Fuploads%2Fgit-blob-8387dbb4ea8b5dd906239de9eb5585796e03045b%2FmaintenancePage.png?alt=media)

{% hint style="info" %}
Two different pages are shown during an upgrade, depending on how the upgrade runs:

* The **maintenance page** is shown while an upgrade is pending and waiting for an administrator to run it.
* The **upgrading page** is shown while an [unattended upgrade](/umbraco-cms/get-started/upgrading-and-migrating/upgrade-unattended.md) runs in the background.

Customizing one does not change the other. This article covers the maintenance page. To customize the upgrading page, use the `UpgradingViewPath` setting instead.
{% endhint %}

## Customize the maintenance page

The following guide will take you through the steps to customize and brand the default maintenance page.

There are two ways to do this. Configuring a view path is recommended. The view then lives alongside the rest of your views, and a mistake in the path is reported instead of being ignored.

{% hint style="info" %}
Both approaches require Umbraco 18.3 or later. In earlier versions, the default maintenance page could not be replaced.
{% endhint %}

### Configure your own view

1. Add a new file to your project, for example `Views/Maintenance.cshtml`.
2. Add your custom markup to the file.
3. Open the project `appSettings.json` file.
4. Add the following configuration, pointing at your file:

{% code title="appSettings.json" %}

```json
{
    "Umbraco": {
        "CMS": {
            "Global": {
                "MaintenanceViewPath": "~/Views/Maintenance.cshtml"
            }
        }
    }
}
```

{% endcode %}

### Replace the default view

Alternatively, add a file at the location the default view uses. Umbraco then renders your file instead of the one built into the CMS.

1. Go to the root of your Umbraco project files.
2. Open the `umbraco` folder, and create a new folder called `UmbracoWebsite` if it does not already exist.
3. Add a new file called `Maintenance.cshtml`.
4. Add your custom markup to the file.

{% hint style="warning" %}
The folder and file names must match exactly, including the casing. If the path does not match, Umbraco renders its default page and no error is shown.
{% endhint %}

{% hint style="warning" %}
Keeping the Umbraco project in Upgrade mode for a longer time is not recommended. Most migrations can be executed while the website continues to work.
{% endhint %}

## Disable the maintenance page

As most upgrades can be done without the website having to restart or go down, the maintenance page can be disabled.

1. Open the project `appSettings.json` file.
2. Add the following configuration:

{% code title="appSettings.json" %}

```json
{
    "Umbraco": {
        "CMS": {
            "Global": {
                "ShowMaintenancePageWhenInUpgradeState": false
            }
        }
    }
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-cms/run-in-production/tutorials/create-a-custom-maintenance-page.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.