The context.xml file is an optional file which contains a <Context> tag (Context Fragment) for a single Tomcat web application. This can be used to define certain behaviours for your application, JNDI resources and other settings.

The context.xml file was introduced in Tomcat 5, to remove Context settings from the server.xml file.

The Context Fragment can be embedded in server.xml, placed in the <CATALINA>/conf folder, or placed inside each application in the META-INF folder in a file called context.xml. The META-INF method is preferred as this means changes to the context don't require Tomcat to be restarted. You can restart your application by modifying web.xml when automatic reloading is active, or reloading manually with the Tomcat Manager.

Your context.xml file should be installed in the META-INF folder of your application, as META-INF/context.xml. The META-INF folder belongs at the same level as WEB-INF (not inside it).


Surprisingly, not many developers use this file within their applications yet, although it is very useful. Switching to the use of a context.xml file removes all dependencies from server.xml, making the application much more portable and easier to deploy.

Example context.xml file

This file provides a JNDI resource representing a MySQL datasource, and a security realm.

<?xml version="1.0" encoding="UTF-8"?>
    <!-- Specify a JDBC datasource -->
    <Resource name="jdbc/mydatabase" 
              validationQuery="select 1"

    <!-- Specify the security realm and location of the users file
    <Realm className="org.apache.catalina.realm.MemoryRealm" 
           pathname="/tomcat/webapps/ROOT/WEB-INF/users.xml" />

Accessing the Datasource in the above example

The datasource in the above example can be accessed in your java code with the following line:
// Get DataSource
Context ctx = new InitialContext();
DataSource ds = (DataSource)ctx.lookup("java:comp/env/jdbc/mydatabase");
// Get Connection and Statement
Connection c = ds.getConnection();
Statement s = c.createStatement();

Additional databases can be added by adding an extra <Resource> element to the context.xml file, with a different name (eg: jdbc/customerDatabase).

Accessing the Security Realm in the above example

The security realm in the above example requires further setup in web.xml. For more details, see the article Securing your site with Container Managed Security.


  • Some examples show path and docBase attributes in the <Context> tag. These are required if the context tag is in server.xml, but in context.xml they are optional, and often just cause deployment problems (eg: if the application is deployed with a different name). It is easier (and better) to leave them out, making the context name automatic. In this case, just use <Context> with no attributes, as in the above example.
  • Default settings for all Contexts are defined in the context.xml.default file in the <CATALINA>/conf folder

Gotchas / Troubleshooting / Debugging JNDI DataSource issues

  • JNDI issues are difficult to debug, as there is no debug output, so if you have problems, check this list
  • With a JNDI datasource, make sure to include the JDBC driver in <CATALINA/common/lib or it will not load
  • If a JNDI datasource does not work, ensure the connection details are correct by connecting a different way (eg: telnet or the mysql command client using the same details)
  • deployXML must be set to false (the default) in the <Host> entry in server.xml, or the context.xml file will be ignored
  • Tomcat 5.5 and Tomcat 6 copy the context.xml file to <CATALINA>/conf/Standalone after the first the successful deployment, and do not remove or update the file unless the application is undeployed. If you change your context.xml file and find it still doesn't work, or your changes are ignored, delete any files in the <CATALINA>/conf/Standalone folder to ensure they are redeployed correctly. Tomcat 7 does not have this problem, unless copyXML is set false (default is true. Sites hosted at Metawerx do not have this problem with any version due to our custom setup.

See Also

metawerx specific

referring pages