The legacy wiki pages are here for reference purposes only.
For up-to-date information make sure to check the documentation section.

The /config/404handlers.config contains the definitions which handler will be used to handle not found requests in Umbraco. The file has by default the following content:

<?xml version="1.0" encoding="utf-8" ?>
<notFound assembly="umbraco" type="SearchForAlias" />
<notFound assembly="umbraco" type="SearchForTemplate"/>
<notFound assembly="umbraco" type="SearchForProfile"/>
<notFound assembly="umbraco" type="handle404"/>

You can easily add your own not found handler. Therefore you have to add a new entry like this:

<notFound assembly="ASSEMBLYNAME" namespace="YOURNAMESPACE" type="HANDLERCLASS" />


Assembly: The assembly property defines the name of the dll without the file extensions.

Type: The name of the class which implements the INotFoundHandler interface.

Namespace: Is the Namespace other than the assembly name you have to add the namespace under which the handler class is defined. Is the namespace the same as the assembly name you can leave out this attribute.

Entry Example:

Let's say you have a class named "MyNotFoundHandler" with is defined in the namespace "MyLibrary.Handlers" but the complete project is only named "MyLibrary" and so it is compiled to MyLibrary.dll. Then you have to add the following entry:

<notFound assembly="MyLibrary" namespace="MyLibrary.Handlers" type="MyNotFoundHandler" />

Entries Order:

It's important to know that the order in which the entries are placed in the file also defines the order in which the handlers are executed. So if you want to be sure that your handler will be the first handler insert it as the first entry.


How to implement your own 404 handler is the community mothership for Umbraco, the open source cms. With a friendly forum for all your questions, a comprehensive documentation and a ton of packages from the community. This site is running Umbraco version 7.5.2