appengine-web.xml Reference

In addition to the web.xml deployment descriptor, an App Engine Java application uses a configuration file, named appengine-web.xml, to specify the app's registered application ID and the version identifier of the latest code, and to identify which files in the app's WAR are static files (like images) and which are resource files used by the application. The appcfg command uses this information when you upload the app.


The following example is a minimal file that specifies the application ID, a version identifier, and no static files or resource files:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">


An App Engine Java app must have a file named appengine-web.xml in its WAR, in the directory WEB-INF/. This is an XML file whose root element is <appengine-web-app>.

You can find the DTD and schema specifications for this file in the SDK's docs/ directory.

Element Description

Not required if you deploy your app using the gcloud app deploy command. The gcloud-based tooling (Intellij, Gradle, and the new Maven plug-ins) ignore this element and get the project ID from the gcloud config project property. The <application> element contains the application's project ID. This is the project ID you register when you create your project in the Google Cloud Platform Console. When you upload your app, appcfg gets the project ID from this file.


Optional. It's possible to reduce request latency by configuring your application to asynchronously write HTTP session data to the datastore:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->

With async session persistence turned on, App Engine will submit a Task Queue task to write session data to the datastore before writing the data to memcache. By default the task will be submitted to the `default` queue. If you'd like to use a different queue, add the `queue-name` attribute:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->

Session data is always written synchronously to memcache. If a request tries to read the session data when memcache is not available (or the session data has been flushed), it will fail over to the datastore, which might not yet have the most recent session data. This means that asynchronous session persistence can cause your application to see stale session data. However, for most applications the latency benefit far outweighs the risk.

<auto-id-policy> Optional. If you are setting entity identifiers automatically, you can change the method employed by setting the auto ID policy. The following are valid options:
Default. Uses scattered auto IDs that are large well-distributed integers that are small enough to be represented by 64-bit floats.
The legacy option will be deprecated in a future release and will eventually be removed. For more information, see the blog post announcing this change.

Optional. For a full explanation, see the automatic scaling section.


Optional. For a full explanation, see the basic scaling section.


Optional. The appengine-web.xml file can define environment variables that are set when the application is running.

  <env-var name="DEFAULT_ENCODING" value="UTF-8" />

To avoid conflicts with your local environment, the development server does not set environment variables based on this file, and requires that the local environment have these variables already set to matching values.

dev_appserver war

When deployed to App Engine, the environment is created with these variables already set.


Optional. Before an application can receive email or XMPP messages, the application must be configured to enable the service. You enable the service for a Java app by including an <inbound-services> section in the appengine-web.xml file.

The following inbound services are available:

Registers your application for notifications when a client connects or disconnects from a channel.
Allows your application to receive mail.
Allows your application to receive instant messages.
Allows your application to receive a user's chat presence.
Allows your application to receive user subscription POSTs.
Enables warmup requests.

Optional. The instance class size for this module.

The following instance classes are available when specifying different scaling options:

When using automatic scaling, the F1, F2, F4, and F4_1G instance classes are available.
Default: F1 is assigned if you do not specify an instance class along with the automatic_scaling element.
When using basic scaling, the B1, B2, B4, B4_1G, and B8 instance classes are available.
Default: B2 is assigned if you do not specify a instance class along with the basic_scaling element.
When using manual scaling, the B1, B2, B4, B4_1G, and B8 instance classes are available.
Default: B2 is assigned if you do not specify a instance class along with the manual_scaling element.

Optional. For a full explanation, see the manual scaling section.


Optional. App Engine uses a "precompilation" process with the Java bytecode of an app to enhance the performance of the app in the Java runtime environment. Precompiled code functions identically to the original bytecode.

If for some reason you prefer that your app not use precompilation, you can turn it off by adding the following to your appengine-web.xml file:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <!-- ... -->

Note: Modules are now named Services and services are still declared in appengine-web.xml files as modules, for example: <module>service_name</module>.

Required if creating a service. Optional for the default service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. It cannot be longer than 63 characters and cannot start or end with a hyphen. Choose a unique name for each service and each version. Don't reuse names between services and versions.

Also see service.


Optional. The <public-root> is a directory in your application that contains the static files for your application. When a request for a static file is made, the <public-root> for your application is prepended to the request path. This gives the path of an application file containing the content that is being requested.

The default <public-root> is /.

For example, the following would map the URL path /index.html to the application file path /static/index.html:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <!-- ... -->

Optional. The files that listed in the <resource-files> element are accessible by the application code using the filesystem. These files are stored on the application servers with the app as opposed to how static files are stored and served.

The <resource-files> element can contain the following elements:

An <include> element designates the files as resource files and available to your application code. These files are only available to your code on a read-only basis and not for traffic serving. Including and excluding files.

Files and directories matching <exclude> patterns will not be uploaded or available to your application code. However, these files and directories will still be accessible to your application when running on the local Development Server. For more information, see Including and excluding files.

  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />

This example demonstrates how to designate all .xml files as resource files except those in the feeds/ directory and all of its subdirectories.

App Engine resource files are read using or javax.servlet.ServletContext.getResource/getResourceAsStream. They are not accessible via Class.getResourceAsStream().


Services were formerly known as modules.

Currently, defining a service as: <service>service_name</service > is supported only by gcloud app commands.


Optional. App Engine includes an implementation of sessions, using the servlet session interface. The implementation stores session data in the App Engine datastore for persistence, and also uses memcache for speed. As with most other servlet containers, the session attributes that are set with `session.setAttribute()` during the request are persisted at the end of the request.

This feature is off by default. To turn it on, add the following to appengine-web.xml:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <!-- ... -->

The implementation creates datastore entities of the kind _ah_SESSION, and memcache entries using keys with a prefix of _ahs.

Note: Because App Engine stores session data in the datastore and memcache, all values stored in the session must implement the interface.

See async-session-persistance element for reducing the latency of the storage of session data.


Optional. By default, any user can access any URL using either HTTP or HTTPS. You can configure an app to require HTTPS for certain URLs in the deployment descriptor. See Deployment Descriptor: Secure URLs.

If you want to disallow the use of HTTPS for the application, put the following in the appengine-web.xml file:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="">
  <!-- ... -->
  <!-- ... -->

There is no way to disallow HTTPS for some URL paths and not others in the Java runtime environment.


Optional. When certain errors occur, App Engine serves a generic error page. You can configure your app to serve a custom static file instead of these generic error pages, so long as the custom error data is less than 10 kilobytes. You can set up different static files to be served for each supported error code by specifying the files in your app's appengine-web.xml file. To serve custom error pages, add a <static-error-handlers> section to your appengine-web.xml, as ins this example:

  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />

Warning: Make sure that the path to the error response file does not overlap with static file handler paths.

Each file entry indicates a static file that should be served in place of the generic error response. The error-code indicates which error code should cause the associated file to be served. Supported error codes are as follows:

Indicates that the app has exceeded a resource quota.
This option serves this error page to any client blocked by your app's DoS Protection configuration.