Techie BabajiLearn to Code. Build Real Skills.
IIS (Internet Information Services) · Performance & Behaviour

Custom Error Pages

Users should see friendly error pages; administrators should see details — but only on the server itself.

Intermediate 5 min Lesson 23 of 33Covers IIS 10 on Windows Server 2019/2022/2025 and Windows 10/11.
Before you start:Default Document and Directory Browsing
0/33 in IIS
On this page · 5 min · Intermediate

On this page

  1. In simple words
  2. Learning objectives
  3. Explanation
  4. Code example
  5. Step by step
  6. Real-world use
  7. Common mistakes
  8. Best practices
  9. Remember this
  10. Practice exercise
  11. Mini quiz
  12. Related topics
  13. My notes
Reading time
5 min
Difficulty
Intermediate
Updated
Oct 30, 2026

Related tutorials

Interview questions

In simple words#

Detailed errors are the mechanic’s diagnostic report — useful for staff, scary and risky to show customers. Custom error pages are the polite “sorry, this counter is closed” sign for the public.

httpErrors
IIS error page configuration.
DetailedLocalOnly
Details on the server, friendly pages for remote users (default).
existingResponse
Whether IIS replaces errors produced by your app.

Learning objectives#

  • Configure custom error pages
  • Show detailed errors only locally
  • Work with ASP.NET Core error responses
  • Avoid leaking stack traces

Explanation#

errorMode: DetailedLocalOnly (default), Custom (always friendly) or Detailed (always details — never in production).

Map status codes to pages: 404 → /errors/404.html, 500 → /errors/500.html.

existingResponse="PassThrough" keeps responses your app already produced (e.g. JSON ProblemDetails from an API); Replace overwrites them.

For APIs, let the app return JSON errors and avoid IIS HTML error pages.

Code example: Friendly error pages for a website#

XMLweb.config Illustrative
<system.webServer>
  <httpErrors errorMode="DetailedLocalOnly" existingResponse="Auto">
    <remove statusCode="404" subStatusCode="-1" />
    <remove statusCode="500" subStatusCode="-1" />
    <error statusCode="404" path="/errors/404.html" responseMode="ExecuteURL" />
    <error statusCode="500" path="/errors/500.html" responseMode="ExecuteURL" />
  </httpErrors>
</system.webServer>


<!-- For an API application at /api: keep the app's JSON errors -->
<!-- <httpErrors existingResponse="PassThrough" /> -->
Expected output
Visitors see the branded 404 and 500 pages; administrators browsing on the server still see detailed IIS errors.

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

  1. DetailedLocalOnly protects details from remote users.
  2. Existing mappings are removed before adding new ones.
  3. ExecuteURL serves the page while keeping the status code.
  4. APIs use PassThrough to keep their JSON errors.

Real-world use case#

A shop shows a helpful 404 page with search and popular categories instead of the default IIS error.

Common mistakes#

errorMode="Detailed" in production

Exposes paths, module names and configuration. Use DetailedLocalOnly or Custom.

Error pages returning 200

Search engines index them as real pages. Keep the original status code.

Best practices#

  • DetailedLocalOnly or Custom in production
  • Branded 404 with search
  • PassThrough for APIs
  • Keep correct status codes

Remember this#

Details for admins, friendly pages for users.

ExecuteURL keeps the status code.

APIs → PassThrough JSON.

Practice exercise#

Your task: Make an API application keep its own error responses.

Show solution
XML Illustrative
<system.webServer>
  <httpErrors existingResponse="PassThrough" />
</system.webServer>

Mini quiz#

Custom Error Pages quizMultiple choice Question 1 of 1

Which errorMode shows details only to requests from the server itself?

Score so far: 0/0

Want more? Practise all IIS MCQs · IIS interview questions

My notes#

Saved in this browser.

Progress is saved in this browser. Sign in to sync.