We welcome user feedback and feature requests!

Enable users to create custom error pages for 403 and 503 service unavailable messages

Currently 503 errors (service unavailable) present a blank white page with "service unavailable" to the users which is far from professional for us. It would be far better if we could provide a custom 503 page which would include a logo etc., and some text along the lines of "We apologise for the inconvenience, we are working on it. These issues usually resolve in about five minutes. please contact support for further help if required." or something similar.... This error might be caused by Azure network issues, so away from the web app instance.

It would also be helpful if this were possible for 403s as well. However 503 is the most important.

I have raised this idea before, but it seems to have disappeared.

I am pretty surprised that we cannot do this already.


728 votes
Sign in
or sign in with
  • facebook
  • google
    Password icon
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    Anonymous shared this idea  ·   ·  Flag idea as inappropriate…  ·  Admin →


    Sign in
    or sign in with
    • facebook
    • google
      Password icon
      Signed in as (Sign out)
      • Kishan Shrestha commented  ·   ·  Flag as inappropriate

        Hello, Azure App Service Team
        It seems to be quite demanding features that devs/devops like to have. Will this be looked at some stage, early will be better as its been going over a 2 years now.

      • Anonymous commented  ·   ·  Flag as inappropriate

        For Azure Team,
        Dear Azure team, we want to provide normal user experience, when Azure web app is down for maintenance or any other reasons, currently 403, 503 pages have only one effect, customers thinking that the company stopped the activities.
        Please put it on priority !

        Thanks in advance,

      • Targa78 commented  ·   ·  Flag as inappropriate

        My company plan to host a major Web application on Azure, but it is a blocker for us. In term of brand image this lack of feature is a real problem.

      • Anonymous commented  ·   ·  Flag as inappropriate

        A workaround for stopped apps when using the Standard + plans you can create a slot (let's call it service-under-maintenance) deploy a static website that is user friendly and switch that deployment slot with production slot. Then when you are ready with your changes and you want production back on deploy to service-under-maintenance (which now has the old production code) and swap it again with production.

      • Saurabh commented  ·   ·  Flag as inappropriate

        Azure support team, I am wondering how difficult is this feature for you guys to implement? Simply, let the site owner control 403, 503 pages for their respective sites. Why can't you deliver this update quickly?

      • Will Hancock commented  ·   ·  Flag as inappropriate

        My Origin is down. There is no web.config. I don't want to give my users a white screen. I want the CDN to pull from storage or host a static custom HTML error page that I can upload... See Amazon CloudFront for an example; http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html

        Codes; - but really its the origin 500's where this is really helpful - response timeout or not reachable.

        400, 403, 404, 405, 414, 416
        500, 501, 502, 503, 504

      • Duncan Smart commented  ·   ·  Flag as inappropriate

        Dear "Azure App Service Team" you have misunderstood the issue here. The 503 pages come from the Azure infrastructure reverse proxy, not the IIS instance running the app. When the site is stopped or restarted from the portal, the app's web.config is not going to help.

      • MM commented  ·   ·  Flag as inappropriate

        This simply is not "completed" with the web.config solution.

      • Anthony Burns commented  ·   ·  Flag as inappropriate

        How can you close it when there are plenty of people highlighting that the "solutions" below don't even work?

      • Marc Climent commented  ·   ·  Flag as inappropriate

        This is by no means closed, if the application is unavailable, web.config is not even read so the solutions proposed don't work.
        In our case, that we are using client certificates, if authentication fails (at ARR level) then Azure shows a 403 without event hitting our app.

      • Matt P. commented  ·   ·  Flag as inappropriate

        One of our web applications that is hosted with an Azure App Service has a 3rd party api that is required and sometimes has planned outages for maintenance. Since our site is not usable when this api is unavailable, we would like to be able to stop the site and display a friendly message to the users that it is unavailable and when it will be back online. Currently you see the default blue screen stating the app is off or there are problems. There should be a way to achieve this similar to the IIS app_offline.htm method but without requiring modifying the filesystem to add/remove that file. Maybe allow the user to specify a file name that is served when the app service is stopped and allow that to be deployed with the site?

      • Bryan Lewis commented  ·   ·  Flag as inappropriate

        I have the same issue as Anthony. I have added the relevant web.config lines as listed by the Azure Team and an HTML file. Still get the default blue screen when stopped.

      • Anthony Burns commented  ·   ·  Flag as inappropriate

        Has anyone had any success getting this to work? I've tried adding the relevant section to my web.config along with a suitable html file, but when I stop the app from the portal, I still get the standard blue and white Azure "Error 403 - This web app is stopped." page.

      • Paul Sterling commented  ·   ·  Flag as inappropriate

        In particular, almost any content than the default 503 response would be an improvement. Certainly if a user could define the content that would be great. The current:

        HTTP Error 503. The service is unavailable.

        Can appear "often" for Asp.Net apps that restart or have frequent deployments causing restarts.

      • AdminAzure App Service team (Admin, Microsoft Azure) commented  ·   ·  Flag as inappropriate

        @Trevor: This has actually been possible for quite sometime.

        The sample is just a sample, the key is the sections of the Web.config which handles the Custom Errors pages:

        <httpErrors errorMode="Custom" allowAbsolutePathsWhenDelegated="true">
        <remove statusCode="403" />
        <error statusCode="403"
        path="%HOME%\site\wwwroot\errors\403.htm" />

        You need to add this section in the web.config for your application. If you don't have a web.config, you will need to create (or copy) one in order to configure this for your application.

        The "Deploy to Azure" button is simply a way to deploy the sample, such that you can see the results of the web.config settings that are applied as part of the application. This is not applying anything to existing resources.

      • Trevor Paesl commented  ·   ·  Flag as inappropriate

        Azure App Service Team: Glad to see that this may now be a possibility. Thanks! Can you please give a little background on how this actually works?

        I see the github repo. I know I can fork it and update my fork with my own branding. Then I see the azuredeploy.json file which has a reference to the repo's url. I can update my fork's json file with my repo instead. So assuming that's all correct, whats the magic that happens in Azure when I push the "Purchase" button in the Azure Portal after I click the "Deploy to Azure" button?

        I can see that I select a resource group and regional data center in the Azure Portal. Does this script update all my web apps within that resource group (since I didn't select them explicitly)? Also, how and what are the app(s) changed? How can I see what was updated and how can I update or undo it in the future?

      • AdminAzure App Service team (Admin, Microsoft Azure) commented  ·   ·  Flag as inappropriate

        We have created a sample which shows how to customize the httpErrors pages. The code is available here: https://github.com/SyntaxC4-MSFT/AppService-CustomErrorPages

        The example covers 403, but it could be duplicated for other error pages. One thing to note, is that we are still confirming if the Authorization/Authentication module will respect these pages. We will update the sample if there are any additional items that we need to cover to enable that scenario.

      ← Previous 1

      Feedback and Knowledge Base