The new way to do a 404 Umbraco Handler

Hello all,
As you may or may not be aware I have been building a new Umbraco starter kit called CWS Start. In this package I wanted to have a 404 page setup for the site. Currently the way to setup a 404 page is to put a node ID in the umbracosettings.config file. My only concern with this approach is that if you delete the node and recreate the node then the 404 will stop working.

So I decided to ask the Umbraco community how they do 404’s and I got a fantastic response from the community.

Stefan & Lee K gave me some fantastic answers and filled me on the new Request pipeline in Umbraco and a way on how to add a ContentFinder to Umbraco, aka the new way of doing 404 handlers in Umbraco 6.1 and any other type of content finders.

Show me the code!

    public class _404iLastChanceFinder : IContentFinder
        public bool TryFindContent(PublishedContentRequest contentRequest)
            //Check request is a 404
            if (contentRequest.Is404)
                //Get the home node
                var home = contentRequest.RoutingContext.UmbracoContext.ContentCache.GetAtRoot().Single(x => x.DocumentTypeAlias == "CWS-Home");

                //Get the 404 node
                var notFoundNode = home.Children.Single(x => x.DocumentTypeAlias == "CWS-404");

                //Set Response Status to be HTTP 404
                contentRequest.SetResponseStatus(404, "404 Page Not Found");

                //Set the node to be the not found node
                contentRequest.PublishedContent = notFoundNode;

            //Not sure about this line - copied from Lee K's GIST
            return contentRequest.PublishedContent != null;

And then we need to register this in Umbraco on App Startup like so:

        protected override void ApplicationStarting(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
            //On application starting event...
            //Add to the ContentFinder resolver collection our custom 404 Content Finder resolver
            ContentLastChanceFinderResolver.Current.SetFinder(new _404iLastChanceFinder());

There are other use cases for IContentFinders and Lee K has a great little example he posted to Gist

11 thoughts on “The new way to do a 404 Umbraco Handler

  1. hey warren

    Nice example, tryed it but it dosnt redirect to my page it still shows the old “ugly error” page ?

    did u set any settings to make it by pass that ?

      1. hey warren

        hmmm i upgraded a site from 6.0.2 to 6.1.4 to get this to work and the code is firering as u say i can see it hits my breakpoint. but it shows me the old one any ideas on what configuration i am missing ?

      2. Hiya that sounds very odd.
        You have to pass a content node back for it to display.

        Can you post your code on a Gist please. But my suspicion is that the node you are trying to find in the site as your 404 node can’t be found and hence returning null.

  2. ok got it working on a clean 6.1.2 install but my upgraded one is still not working.

    btw I don’t think u need to set the status code once more cause u already have a 404 request, due to your if(contentRequest.Is404)

    cheers for and awsome blog mate.

  3. Very nice implementation of 404 handling.

    Doing coding and testing I ran into a problem with getting the correct PublishedContent node to show. This could be due to two reasons. Reason 2 was my fix:

    1. Check umbracoSettings.config and make sure your not handling error pages here in the section. If so, comment them out while testing. ( tag must be present).
    2. This will not work if web.config and is set. Instead change the ‘existingResponse’ setting to “Passthrough”. However I ended up not using at all and went back to to handle a generic statusCode 500 html error page.

  4. Hey Warren, four years on, is this still the best/only way to implement 404 handling?
    Also — or mainly — as a noob I’m stuck. I don’t see an App-Start folder in the project I’m working on. Where do I put that override method? Which class?


  5. Hi Warren,

    It’s seems like this doesn’t work for pages of which the document type has no template. It still shows the default (“ugly”) 404 error page. Do you perhaps know how to solve this?

Leave a Reply to Peter Cancel reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.