Default Status Code Pages

Enable built-in error pages so 404, 500, and similar responses return consistent content.

Full source

File: pwsh/tutorial/examples/17.1-StatusCodePages-Default.ps1

#
# Sample: Default Status Code Pages
# This script demonstrates how to set up a Kestrun server with default status code pages.
# The server will show default error pages for 404, 500, and other HTTP error status codes.
# FileName: 17.1-StatusCodePages-Default.ps1
#

param(
    [int]$Port = 5000,
    [IPAddress]$IPAddress = [IPAddress]::Loopback # Use 'Loopback' for safety in tests/examples
)

# Step 1: Set up logging
New-KrLogger | Add-KrSinkConsole | Register-KrLogger -Name 'console' -SetAsDefault

# Step 2: Create a new Kestrun server
New-KrServer -Name 'Default Status Code Pages Server'

# Step 3: Add a listener on the specified port and IP address
Add-KrEndpoint -Port $Port -IPAddress $IPAddress

# Step 4: Enable default status code pages middleware
Enable-KrStatusCodePage

# Step 5: Enable Kestrun configuration
Enable-KrConfiguration

# Step 6: Map a normal route
Add-KrMapRoute -Verbs Get -Pattern '/hello' -ScriptBlock {
    Write-KrTextResponse -InputObject 'Hello, World!' -StatusCode 200
}

# Map routes that trigger different status codes
Add-KrMapRoute -Verbs Get -Pattern '/notfound' -ScriptBlock {
    # Return empty response with 404 status to trigger custom error page
    Write-KrStatusResponse -StatusCode 404
}

Add-KrMapRoute -Verbs Get -Pattern '/error' -ScriptBlock {
    # Return empty response with 500 status to trigger custom error page
    Write-KrStatusResponse -StatusCode 500
}

Add-KrMapRoute -Verbs Get -Pattern '/forbidden' -ScriptBlock {
    # Return empty response with 403 status to trigger custom error page
    Write-KrStatusResponse -StatusCode 403
}

Add-KrMapRoute -Verbs Get -Pattern '/unauthorized' -ScriptBlock {
    # Return empty response with 401 status to trigger custom error page
    Write-KrStatusResponse -StatusCode 401
}

Write-Host "Server starting on http://$($IPAddress):$Port" -ForegroundColor Green
Write-Host 'Try these URLs:' -ForegroundColor Yellow
Write-Host "  http://$($IPAddress):$Port/hello        - Styled welcome page with test links" -ForegroundColor Cyan
Write-Host "  http://$($IPAddress):$Port/notfound     - Styled 404 error page" -ForegroundColor Cyan
Write-Host "  http://$($IPAddress):$Port/error        - Styled 500 error page" -ForegroundColor Cyan
Write-Host "  http://$($IPAddress):$Port/forbidden    - Styled 403 error page" -ForegroundColor Cyan
Write-Host "  http://$($IPAddress):$Port/unauthorized - Styled 401 error page" -ForegroundColor Cyan
Write-Host "  http://$($IPAddress):$Port/missing      - Styled 404 for unmapped route" -ForegroundColor Cyan


# Step 7: Start the server
Start-KrServer -CloseLogsOnExit

Step-by-step

  1. Logging: Register console logger as default.
  2. Server: Create the server host named ‘Default Status Code Pages Server’.
  3. Listener: Bind to 127.0.0.1:5000.
  4. Middleware: Enable default status code pages.
  5. Configuration: Apply staged configuration.
  6. Routes: Map /hello and simple routes that set 404/500/403/401.
  7. Start: Start the server.

Try it 

curl -i http://127.0.0.1:5000/hello
curl -i http://127.0.0.1:5000/notfound
curl -i http://127.0.0.1:5000/error
curl -i http://127.0.0.1:5000/forbidden
curl -i http://127.0.0.1:5000/unauthorized
curl -i http://127.0.0.1:5000/missing

PowerShell equivalents:

# 200 OK normal route
Invoke-WebRequest -Uri http://127.0.0.1:5000/hello | Select-Object StatusCode, Content

# Non-2xx examples (avoid exceptions on 4xx/5xx)
Invoke-WebRequest -Uri http://127.0.0.1:5000/notfound    -SkipHttpErrorCheck | Select-Object StatusCode | Format-List
Invoke-WebRequest -Uri http://127.0.0.1:5000/error       -SkipHttpErrorCheck | Select-Object StatusCode | Format-List
Invoke-WebRequest -Uri http://127.0.0.1:5000/forbidden   -SkipHttpErrorCheck | Select-Object StatusCode | Format-List
Invoke-WebRequest -Uri http://127.0.0.1:5000/unauthorized -SkipHttpErrorCheck | Select-Object StatusCode | Format-List
Invoke-WebRequest -Uri http://127.0.0.1:5000/missing     -SkipHttpErrorCheck | Select-Object StatusCode | Format-List

Troubleshooting

Symptom Likely cause Fix
Plain text body, not styled Templates/assets not enabled Ensure default status code pages are enabled before routes
200 OK for errors Route writes content after setting status Use Write-KrStatusResponse only, or ensure no body is written
No response body for 4xx/5xx Upstream swallowed content Verify other middleware isn’t overriding responses

References

Previous / Next

Previous: None Next: Custom Options