Add a Catch-All Sitemap Item to Generate a Dynamic 404 Page

When you define a sitemap like the following example:

/sitemap:
  /home:
  /news:
    /**:
  /events:
    /**:

URLs such as /home, /news/2019, /news/2019/foo, and /events/2019 are handled by the sitemap. However, URLs like /home/foo or /files/2010 do not match any sitemap item. This situation often occurs after migrating a site from another platform, where legacy links (for example, /home.aspx) may still exist in search engines or external sources.

If a URL does not match any sitemap item, the system throws a org.hippoecm.hst.core.container.ContainerNotFoundException. By default, this exception is handled by the web container and can be mapped in web.xml. For more information, see Handle Error Codes and Exceptions in web.xml. However, handling errors in web.xml limits you to static error pages. You cannot use dynamic features such as a repository-driven menu or display URL suggestions on the error page.

Configure a Catch-All Sitemap Item

To support dynamic error pages, extend your sitemap as follows:

/sitemap:
  /home:
  /news:
    /**:
  /events:
    /**:
  /**:

Add a /** matcher at the root level. The position of this matcher does not affect matching because HST URL matching selects the most specific match, not the first one. Any URL that does not match home, news, or events (including their subitems) will match the root-level /** item.

From the /** sitemap item, reference an hst:componentconfigurationid that defines the error page components. For example:

/pages:
  /standard:
  /errorpage:
    /body:     

In this structure, the errorpage configuration can extend standard and include a custom body. For example, you can use the following component class:

hst:componentclassname: org.onehippo.cms7.essentials.components.EssentialsPageNotFoundComponent

The body node can contain custom logic, such as searching for documents related to the requested URL.

The EssentialsPageNotFoundComponent class is provided by Essentials. It sets the HTTP response status code to 404 (Not Found):

public class EssentialsPageNotFoundComponent extends CommonComponent {
    @Override
    public void doBeforeRender(final HstRequest request, final HstResponse response) {
        super.doBeforeRender(request, response);
        response.setStatus(HttpServletResponse.SC_NOT_FOUND);
    }
}
copy

This approach enables you to serve dynamic 404 pages with repository-driven content and custom logic, rather than static error pages.