Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: explain new options etc from JETTY-936

Do welcome files need to exist?

By default, yes, welcome files do need to exist. But Jetty can be configured to allow dispatching to welcome files which are servlets.

The welcome file mechanism allows a request to /some/directory/ to be served by the contents of a file like /some/directory/index.html. If there is a servlet mapped to handle the welcome file, it will be called. So if index.jsp is configured as a welcome file, then a request to /some/directory/ will be passed to the JspServlet mapped at *.jsp to handle the /some/directory/index.jsp file.

From Jetty 6.1.16 onwards, the DefaultServlet can dispatch to welcome files which are servlets, even if the files don't exist. However, in order to allow directory listing when the servlet mapping matches, but would point to a nonexistent resource, by default this ability is disabled.

The options related to viewing directories and welcome files are as follows:

  • JSPServlet enabled, index.jsp in welcome file list; this is the default set up in webdefault.xml
  • DefaultServlet's dirAllowed init-param, if true, allows directory listings when the request matches no resources or servlets. Default in webdefault.xml is true
  • DefaultServlet's welcomeServlets init-param, if true, allows for dispatching to welcome files which are servlets even with no accompanying static resource. Default in webdefault.xml is false.

Assuming JSPServlet is called for requests to any file *.jsp, and dirAllowed is true, then the behavior is as follows:


welcomeServlets option, with no existing index.jsp


404s, because it matches against *.jsp in the servlet mapping and dispatches to index.jsp

false (default)

directory listing, because it doesn't try to dispatch to the JSP servlet

In older versions of Jetty, the file MUST exist for the welcome file mechanism to work. Even if is defined as a welcome file, then a request to /some/directory/ will not be passed to a servlet handling *.do for some/directory/ UNLESS THE FILE EXISTS.If unless the file exists.

Welcome files are not prioritized in the order on my welcome-file-list

If your welcome-file-list is a mix of static resources and servlets, note that static resources will always take priority, in the order listed in the welcome-file-list. If no static resources match, then the welcome-file-list is checked again for any matching servlet mappings. This is to avoid any issues, such as above, where a webapp with no file index.jsp will return a 404 if index.jsp is in the welcome-file-list.

Note that the default welcome-file-list contains index.jsp.

How do I work around the need for welcome files to exist, in older versions of Jetty?

If you want an index to be served by a servlet, then I suggest you use a filter
to do the redirection. See the for an example.


In order to use a struts action as a welcome file, you will need to set redirectWelcome in Default ServeltServlet to true. The default is for redirectWelcome to be false, which means the page will be forwarded to, and the action never called.

Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery