dispatch.xml Configuration File

The dispatch.xml allows you to override routing rules. You can use the dispatch.xml to send incoming requests to a specific service (formerly known as modules) based on the path or hostname in the URL.

For more information, see How Requests are Routed.

Deploying the dispatch file

The dispatch.xml file should reside in the WEB-INF directory of the default service. To deploy the dispatch file by itself, use the appcfg update_dispatch command, and specify the directory for the default service. Be sure that all the services mentioned in the file have already been deployed before using the following command:

  • Deploy without altering the currently serving version, replacing with the path to your application main directory:

    appcfg.sh update_dispatch <application directory>
  • Alternatively, cd to the application directory containing the default service, then run the command:

    appcfg.sh update_dispatch .

You can also deploy the dispatch file at the same time you deploy one or more services, by adding the optional auto_update_dispatch flag, which can be used in two forms:

appcfg.sh --auto_update_dispatch update <app-directory>|<files...>
appcfg.sh -D update <app-directory>|<files...>

For more information about the deployment commands, see Deploying a Java 8 App.


The root element in the dispatch.xml file is <dispatch-entries> and each entry is a <dispatch> element that contain the following elements.

The rules that you define in your dispatch file must use HTTP URL patterns that include the "." notation for separating subdomains. URLs defined with the HTTPS "-dot-" notation are not supported.

Dispatch rules are order dependent, and can also apply to the URLs that you define in your cron file.

Element Description

Specifies the name of the service that will handle the requests that match the url pattern.


In the url element, you define the URL pattern, which can include the host name and URL path that are no longer than 100 characters. For the service element, you specify the name of the service that you want handling any incoming requests that match the URL pattern of the url element.

Tip: You can include glob patterns like the * wildcard character in the url element; however, those patterns can be used only before the host name and at the end of the URL path.

A URL pattern that can include the hostname and URL path. Glob characters can be used to match patterns. The Glob characters can be specified only at the beginning of the pattern and end of the pattern.

Note that dispatch rules also apply to URLs that are used in cron configuration or in task queue configuration.

URL paths that begin with /_ah/ are not routed by the dispatch file.


The following is a sample dispatch file that routes requests to http://simple-sample.appspot.com and requests like http://simple-sample.appspot.com/favicon.ico to the default <module>. All static content is served from the default <module>. Mobile requests like http://simple-sample.appspot.com/mobile/ are routed to a mobile frontend, and worker requests like http://simple-sample.appspot.com/work/ are routed to a static backend.

<?xml version="1.0" encoding="UTF-8"?>
      <!-- Default module serves the typical web resources and all static resources. -->
      <!-- Default module serves simple hostname request. -->
      <!-- Send all mobile traffic to the mobile frontend. -->
      <!-- Send all work to the one static backend. -->


The dispatch file can contain up to 20 routing rules. When specifying the URL string, neither the hostname nor the path can be longer than 100 characters.

Deleting all dispatch rules

To delete all dispatch rules:

  1. Edit the contents of the dispatch.xml file to:

    <?xml version="1.0" encoding="UTF-8"?>
  2. Deploy the dispatch.xml file to App Engine.



App Engine standard environment for Java 8