Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article explains how to configure custom error pages on your web app. With App Service you can configure an error page for specific errors that will be presented to users instead of the default error page.
Prerequisite
In this tutorial, we're adding a custom 403 error page to our web app hosted on App Service and test it with an IP restriction. To do so, you need the following:
- a web app hosted on App Service w/ a Premium SKU
- an html file under 10 kb in size
Upload an error page
For this example, we're uploading and testing a 403 error page to present to the user. Name your html file to match the error code (for example, 403.html). Once you have your html file prepared, you can upload it to your web app. In the configuration blade, you should see an Error pages (preview) tab. Click on this tab to view the error page options. If the options are greyed out, you need to upgrade to at least a Premium SKU to use this feature.
Select the error code that you'd like to upload an error page for and click Edit. On the next screen, click the folder icon to select your html file. The file must be in html format and within the 10 kb size limit. Find your .html file and click on the Upload button at the bottom of the screen. Notice the Status in the table updates from Not Configured to Configured. Then click Save to complete the upload.
Confirm error page
Once the custom error page is uploaded and saved, we can trigger and view the page. In this example, we can trigger the 403 error by using an IP restriction however you can also trigger a 403 error page by stopping the site.
To set an IP restriction, go to the Networking blade and click the Enabled with access restrictions link under Inbound traffic configuration.
Under the Site access and rules section, select the +Add button to create an IP restriction.
In the form that follows, you need to change the Action to Deny and fill out the Priority and IP Address Block. In this example, we use the Inbound address found on the Networking blade and we're setting it to /0 (for example, 12.123.12.123/0). This disables all public access when visiting the site.
Once the Add rule form is filled out, select the Add rule button. Then click Save.
Once saved, you need to restart the site for the changes to take effect. Go to your overview page and select browse. You should now see your custom error page load.
Error codes
App Service currently supports three types of error codes that are available to customize:
| Error code | description |
|---|---|
| 403 | Access restrictions |
| 502 | Gateway errors |
| 503 | Service unavailable |
FAQ
- I've uploaded my error page, why doesn't it show when the error is triggered?
Custom error pages are triggered from front end failures. If the error is coming from the app level, it won't trigger or show the configured error page. If you want the error page to show for all requests, check the Apply to all requests box under the configured error code. This will show the error page for all requests matching the status code regardless of where it failed. Note, when this box is checked it will override any existing error pages that are configured for the app.
- Why is the error page feature greyed out?
Error pages are currently a Premium feature. You need to use at least a Premium SKU to enable the feature.
- How can I reference a single error page across multiple apps?
If you need to use the same error page across multiple apps, you can link to your error page hosted in a storage account in your uploaded html file. Upload your error page to a storage account and add the provided storage URL for your page in an <iframe> tag located in the html file uploaded to the app.