Skip To Content

Configure cache consumption

Once you have defined a titling scheme for your map service, the service will immediately begin to try to use the cache. Any ArcGIS application that can display a map or image service will use the cache; however, how the tiles are retrieved and used will vary between each application.

Web apps

You can add your cached map or image service to be used as a basemap or operational layer in your web map.

To connect a cached map service to your web map, you can use an ArcGIS Tiled Map Service layer object.

To connect a cached image service to your web map, you can use an ArcGIS Tiled Image Service layer object.

The tiles are retrieved from the cache directory using REST calls to the map service using the following map tile request: https://<map service URL>/tile/<level>/<row>/<column>.

Troubleshoot web apps

If your map is performing slower than expected, you can examine the URLs of the map images to verify that the app is retrieving the cached tiles.

To verify that your app is retrieving the cached tiles, follow these steps:

  1. Open the application Web Developer tools in your browser.
  2. Click the Network tab in your console.
  3. Zoom and pan the web map.

If you see URLs formatted similarly to the one below in your console, your app is successfully using cached tiles from REST requests.

If you see another URL format, such as exportMap or exportImage, your app is not using your cache.

ArcGIS Pro

To add cached map services to ArcGIS Pro, see Add layers to a map or scene in ArcGIS Pro.

When a request is made for a tile at a scale that matches the scale level in the cache for a given projection, the map service will return the tile directly. However, requests often do not exactly match the scale or projection in a cache. In these instances, the tile from the next closest scale will be requested and resampled to match the scale requested. Resampling is quicker than generating the tile dynamically; however, the process will result in an image that looks different than the original tile.


Map labels that have been cached may be difficult to read at certain scales after the resampling process.

It is recommended that you view the map at scales near the scales the cache was created at to confirm legibility.

ArcGIS Pro caches map and image service content locally to enhance the performance of map and image layers for a session. See Set caching options for more information on how caching in ArcGIS Pro works.

Cached data can also be accessed as a raster dataset in ArcGIS Pro. While caches accessed as rasters cannot be queried, they will allow you to view the tiles when disconnected from the server, as they do not rely on a map service.

Enable clients to cache locally

When displaying cached map or image services, you can allow ArcGIS clients to store tiles locally, preventing them from needing to be retrieved again when a user navigates back to an area they have already viewed.


Users may need to clear their local caches before they will be able to see updates you have made to the cache.

If you update your cache frequently, you can choose to disable the ability for clients to cache tiles locally. Doing so will ensure that users will have the most up-to-date information, rather than older information that may be stored in their local cache.

If local caching is enabled, users can choose whether they store tile caches locally. Users can choose to continually build the local cache, build a new local cache for each application session, or not build a local cache.

Define the cacheControlMaxAge property

When clients send requests to ArcGIS Server to display a map service, the response from the server is typically cached by the browser and reused for a certain period of time. This behavior helps in achieving the best display performance for your content. However, depending on how your cache map or image service and its associated data are used in applications, you can adjust the length of time the browser uses a response in its cache.

When a request is repeated and the maximum age of the cache has not expired, the browser uses the cached response without sending the request to the server. If the maximum age has expired, the browser must send the request to the server and set an IF-NONE-MATCH header with an associated ETag value corresponding to the response in its cache. ArcGIS Server evaluates the request and uses the ETag value to determine if the response has changed. If the response from the server is different than the copy on the browser, the server sends a new response to the browser. If the response is identical to the copy on the browser, the server alerts the browser to continue to use the response in its cache.

For cached map services that do not allow clients to cache tiles locally, the default is 0. This results in the browser always resending a request that ArcGIS Server will process and respond to if the content has changed. This default value works well for most apps.

For cached map services that allow clients to cache tiles locally, the default value is 86,400 seconds (1 day). At this default value, if a request is repeated within 1 day, the browser will use the response stored in its local cache. If your cached map service is not updated frequently, it is recommended that you increase the cacheControlMaxAge property to 30 days (2,592,000 seconds) or longer to minimize network traffic.

To add the cacheControlMaxAge property to your service and edit its default value, do the following:

  1. In a web browser, open the ArcGIS Server Administrator Directory and log in with administrator privileges.

    The URL is formatted

  2. Click services, and choose the map or image service you want to modify from the Services list.

    If you don't see your service listed, it may be in a directory under the root folder.

  3. On the Service - <service name> (<service type>) page, scroll to the bottom and click edit.
  4. On the Service Properties dialog box, locate the "properties" section of the service JSON.
  5. Add the cacheControlMaxAge property to the section and specify the value (in seconds).

    The following is an example:

    "properties": {
      "cacheControlMaxAge": "300",
  6. Click Save Edits.
  7. Verify that the cacheControlMaxAge property and the value you chose appear in the Properties section.

Use a highly available file share

For your on-premises GIS server site cache, you can designate a directory on a highly available file server that uses a Storage Area Network (SAN) or highly available Network Attached Storage (NAS). This is usually configured by your information technology staff.

If your organization has a SAN or NAS with sufficient space for your cache, this will be the easiest and most reliable solution to make your map and image caches highly available.

If you do not have access to such a file server, you can create cache directories on each machine in your deployment as described in the following section.

For highly available systems, you can backup your cache directories in cloud stores. Keep in mind that end users of map or image service caches may experience a performance penalty as tiles are retrieved from a cloud store compared to tile retrieval from a local disk. Also, ensure caches stored in cloud stores use compact v2 storage format.

Configure highly available caches

Storing multiple copies of map and image caches on all machines in the site allows the cache and service to be highly available. Create directories on each machine in the GIS server site and copy all caches to each of these directories. All machines participating in the GIS server site must have access to every cache directory.

Be aware of the following when configuring local cache directories:

  • You cannot use on-demand map caching with services configured with a local cache directory.
  • Geoprocessing tools that update existing caches output to a common site cache directory. If you run these tools, you must move caches to the local cache directories of each machine participating in the GIS server.

Although there is more administrative overhead when implementing cache directories on every machine in the GIS server site, it is the only option when implementing a highly available GIS server in the cloud.

You can also implement this solution in on-premises deployments. This is recommended if you do not have a highly available file server available and your caches are not frequently (or never) updated.

By default, map and image caches are written to a single site cache directory. Follow these steps to configure cache directories on each machine participating in the GIS server site:

  1. Open the ArcGIS service endpoint of the server cache directory. The URL is in the format
  2. Choose the site cache.
  3. Click Edit.
  4. Set Use Local Directory to TRUE.
  5. Specify the path to a local cache directory. Cache directories must be created in the same place on all machines.

    Once set, ArcGIS Server creates caches for map and image services published to that machine in the local cache directory you specified.

  6. Manually copy existing cache data from the site cache directory to each local cache directory.

    Be sure the existing cache has finished building before attempting to copy it.

    You can use rsync to move the cache, for example

    rsync –avx -progress <login>@<location of existing cache> <local cache directory>