Monday, April 18, 2022

Add a Default Error Page in web.xml for Java app in Windows App Service

App Service Windows includes multiple versions of Tomcat. Sometimes, you may want to add custom configurations via web.xml file.


Before talking about how to change web.xml file in App Service windows, let's discuss "what is web.xml"?


Java web applications use a deployment descriptor file to determine how URLs map to servlets, which URLs require authentication, and other information. This file is named web.xml and resides in the app's WAR under the WEB-INF/ directory. web.xml is part of the servlet standard for web applications.


The default Servlet configurations is under ${catalina.home}/conf. For each webapp, the settings could be found under ${catalina.home}/webapps/ROOT/WEB_INF.


When tomcat deploys the application, it reads the generic configurations from conf/web.xml and then WEB-INF/web.xml in the web application. 


It instructs the Tomcat which classes to load, what parameters to set in the context, and how to intercept requests coming from browsers.

There you specify:

  • what servlets (and filters) you want to use and what URLs you want to map them to
  • listeners - classes that are notified when some events happen (context starts, session created, etc)
  • configuration parameters (context-params)
  • error pages, welcome files
  • security constraints

Back to our topic, if you haven't defined a custom error page, you will the default page as below:



To add a custom error page, please follow below steps:

  • Add <error-page></error-page> in web.xml under webapps/ROOT/WEB_INF. For example, my custom error page "error.html" is under root folder /webapp, so I should use "/error.html" in <location></location>.


  • Add your custom error in webapps folder.


  • Build and re-deploy the project to App Service.
  • Now you will see the custom error page replace the default one.



Please kindly note, configurations won't take effect if you add web.xml directly in Kudu site. Tomcats only reads the configurations from war file during startup.

Posted at