Troubleshooting Application Deployment on Tomcat

This page contains troubleshooting tips for:

  • Deploying new applications
  • Replacing and Reloading applications
  • Undeploying applications

Automatic Deployment with autoDeploy

As soon as Tomcat notices the <appname>/WEB-INF/web.xml file inside the webapps folder, it will deploy the application automatically, and it will appear in the Tomcat Manager using the name from the <display-name> tag in your web.xml file. This is handled automatically by Tomcat's autoDeploy feature.

If your application does not deploy automatically, there is either a problem in the web.xml file, the web.xml file is in the wrong location, or autoDeploy is disabled.

Troubleshooting Checklist

  • Make sure your folder is called WEB-INF (in capitals)
  • Make sure the web.xml file is called web.xml (in lower case), and contains a valid deployment descriptor. See the page web.xml - DTD and XSD for different examples depending on your version of Tomcat.
  • If the Tomcat Manager is not installed, and autoDeploy is disabled, you will need to reset your JVM to deploy the application. Do this if necessary.
  • In the Tomcat Manager (http://yoursite/manager/html), is the application listed? Does the running column say "true" or "false"?
  • If the application is not listed, you can try deploying it manually. See Deploying an application with the Tomcat Manager.
  • If listed, and the running column says "false", your web.xml has a problem. Check the Tomcat logs.
  • Errors appear in the Tomcat Manager after a manual deploy or start. If no Tomcat Manager is available, check the logs to see the deployment errors, and then check the error message list below.

Deployment Error Messages

FAIL - Application already exists at path /myNewApp

If this message appears, the /myNewApp application has already been deployed. This may have happened because of Tomcat's autoDeploy feature, or because you have already deployed the application yourself.

The application will be listed in Applications list.

FAIL - Invalid context path myNewApp was specified

This can happen if you forget the leading slash on the application name (myNewApp instead of /myNewApp), or if the folder does not exist.

Check the folder, especially capitilisation of any letters.

FAIL - Failed to deploy application at context path /myNewApp

This typically indicates an error in your web.xml file. Check the Tomcat logs to see more information about the error.

Reloading / Undeploying, and Locked Files

On Windows, JAR files are sometimes locked by Tomcat, making it impossible to reload, undeploy, or replace the locked JAR file. This happens for a few different reasons.

  • If a resource in the JAR file is accessed via URL, and caching is not explicitly disabled by the caller, the JAR file will remain open. This can be sometimes happen with Struts and other Xerces-based applications. In this case, try adding the antiJARLocking="true" attribute to your Context (ie: in the context.xml file or server.xml file) during development. This will prevent the JAR being locked for this specific case only. The JAR is copied to a temporary location and opened from there instead, so startup time is reduced, but it becomes easier to reload the application. When the application is ready to place into a production environment, or if you do not experience this problem, do not use this switch. The default is false.
  • A client (browser) still has an open connection to a resource, forcing a JAR file to stay locked. This can happen with long requests, or with Internet Explorer, which will sometimes maintain a connection to a server that has KeepAlive enabled, while you are on a page, even though the page has already loaded. In this case, close all browser windows (not just the window that is connected to the application), to force IE to close. Then open a new browser window and go directly to the Tomcat Manager and attempt a reload.

Problem not listed

If your error message is not listed above, please add it to this page (by clicking Edit Page or Add Comment), and someone will add a solution.

Also check Debug your app for common deployment exceptions, and JAR files you should never include in your webapp for a list of JAR files that cause issues if you include them in your webapp.

See Also

metawerx specific

referring pages