How to setup SPO Custom Error Page

Do you want a better looking 404 page for modern SharePoint Online Communication Sites? When someone enters a wrong URL of receives a link to a page that has already been deleted, they can be redirected to a Custom Error Page. Here you can explain the situation and direct the visitor to the homepage. Before you can start scripting, you’ll need to set a few configurations. In this article I’ll describe these.

PnP.PowerShell Enterprise Appliation

You’ll need the PnP.PowerShell Enterprise Application registered and access permissions to it. We followed this blog (PnP PowerShell – Consent and Authentication | AgrenPoint Blog) to get it configured. You’ll need the Global Admin role, before running the script below. Be aware that of the PowerShell commands, you’ll need a minimum PowerShell version 7.1!

Custom Error Page

Typically, settings for a site collection are stored in the property bag, so that was the first place I looked and immediately found a reference in the key “vti_filenotfoundpage” to “/sites/ClassicPublishingSite/Pages/PageNotFoundError.aspx”. So this is the place to go. First you need to create a new ‘Custom Error Page’ site in SharePoint Online and edit the home.aspx to the way you want to. For example:

Be aware that you have to configure this property bag for each Hub Site in your tenant. They can all be configured to redirect to the same error page.

PowerShell Script

I used this PowerShell Script and run it in PowerShell version 7.1

$Sites = @( `
    'https://yourtenant.sharepoint.com/'; `
    'https://yourtenant.sharepoint.com/sites/yoursite'; ` 
    'https://yourtenant.sharepoint.com/sites/yoursite_1'; `
    'https://yourtenant.sharepoint.com/sites/yoursite_2'
)

# Needed configuration
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
UnInstall-Module -Name SharePointPnPPowerShellOnline -AllVersions
Install-Module -Name PnP.PowerShell -RequiredVersion 1.12.0 -Force -AllowClobber
Import-Module -Name PnP.PowerShell

foreach ($Site in $Sites) {
    # Connect to SharePoint Online with PnP PowerShell library
    Connect-PnpOnline -Url $Site -UseWebLogin

    # Disable NoScript
    Write-Host "  Disabling NoScript for [$Site]" -ForegroundColor Cyan
    Set-PnPTenantSite -Url $Site -NoScriptSite:$false

    # Sets the value in the property bag.
    Write-Host "  Adding Property Bag Key" -ForegroundColor Cyan
    Set-PnPPropertyBagValue -Key "vti_filenotfoundpage" -Value "/sites/CustomErrorPage/SitePages/Home.aspx"

    # Enable NoScript
    Write-Host "  Enabling NoScript for [$Site]" -ForegroundColor Cyan
    Set-PnPTenantSite -Url $Site -NoScriptSite
}

Write-Host " Script Complete! ;)" -ForegroundColor Green

Result

To test the results, enter a bad URL e.g.

https://yourtenant.sharepoint.com/sites/yoursite/pages/pagewithbrokenlink.aspx

This simple entry into the property bag has enabled this feature with minimal effort