Overwrite a map image layer

In addition to publishing new web layers, you can use ArcGIS Pro to overwrite existing map image layers to reflect changes to a GIS resource or its source data.

You can overwrite an existing map image layer if all of the following conditions are true:

  • You are signed in to your ArcGIS organization with the account that owns the map image layer being overwritten or as an administrator.
  • The location of the existing map image layer in your portal has not changed while the Overwrite Web Layer pane is open.
  • The map image layer is not a hosted map image layer (in other words, it was not published from a web feature layer).

Overwriting a map image layer is similar to sharing a map image layer. You can change most of the properties of a map image layer when you overwrite it, including both properties of the map itself and configuration settings. You can't change the name of the service or its location (the service URL). If you are overwriting a cached map service, see the Cached map image layer considerations section below.

While in the process of overwriting a map image layer, you may decide to save a service definition instead. A service definition compiles information into a single file, allowing you to overwrite the map image layer at a later time. Information about saving a service definition is included in the workflow below. To learn more, see Introduction to saving service definitions.

You can also use ArcPy to overwrite a map image layer to a portal. To learn more, see Automate sharing web layers.

Considerations when overwriting web layers

The existing web layer, including pop-ups and symbology, is always overwritten with what is authored in ArcGIS Pro. If you overwrite a web layer, its associated data is replaced. Changes to the pop-ups or symbology, or any other updates to the web layer after it was initially published, are lost. When overwriting a web layer, the schema of the new layer you are publishing can differ from the schema of the existing web layer if the new layer has different field names, deleted fields, or new fields.

Web maps store pop-ups and symbology separately from web layers. Pop-ups stored in the web map will not be updated if the web layer is overwritten with a newly configured pop-up. If the schema of a web layer changes, you may need to reconfigure your web map's pop-ups and symbology.

For example, you shared a web layer of United States cities and authored a web map that symbolizes the layer using the name field. When you overwrite the existing web layer with a new web layer with the name field renamed to city, the web map still tries to symbolize the layer using the old name field, even though it no longer exists. You must reconfigure the symbology using city as the new field.


Before overwriting a web layer, verify that the IDs assigned to layers and tables in your map match existing service sublayer IDs. Otherwise, overwriting may break web maps consuming the service. For more information, see Assign layer IDs.

Overwrite a map image layer

This workflow explains how to overwrite a map image layer.

  1. To overwrite a web layer, do one of the following:
    • Overwrite an existing web layer with all usable layers in the map. On the Share tab, in the Share As group, click the Web Layer drop-down arrow and click Overwrite Web Layer Overwrite Web Layer.
    • Overwrite an existing web layer with selected layers in the map. Select the layers in the Contents pane. Right-click the selected layers, point to Sharing, and click Overwrite Web Layer Overwrite Web Layer.

    The Overwrite Web Layer dialog box appears.

  2. On the Overwrite Web Layer dialog box, browse to the location of the web layer in your portal and select it. Click OK.

    By default, both map image layers and web feature layers appear on the dialog box. Use the drop-down list at the bottom of the dialog box to control the layer types that appear.

  3. Read the Overwrite Web Layer message and click OK to continue.

    If online edits were made to the web layer, or if features were appended to it, these changes will be overwritten.

    The Overwrite Web Layer pane appears. On the General tab, under Item Details, the name of the web layer is displayed. The name can't be changed.

  4. Under the layer name, choose one of the following options:

    Use the item description from the web layer

    The item description of the existing web layer is preserved. This is the default option.

    Use the item description from the map or layer

    The item description of the existing web layer is overwritten with the metadata of the map or layer.

  5. Optionally, modify the information in the Summary and Tags fields.

    The fields may be empty if you chose to use the item description from the map or layer in the previous step. A summary and tags are required when sharing to an ArcGIS Enterprise 10.9 or earlier portal.

    You can enter a maximum of 128 tags.

  6. Under Data and Layer Type, click Map Image under one of the two data types:
    • Reference registered data—Data that is registered with the server is referenced rather than copied to the server.
    • Copy all data—All data is copied to the server.

    For information about registering data with a server, see Introduction to sharing web layers.

    Under Location, the settings are preset and can't be changed.

  7. Optionally, under Share with, change the settings:
    • Everyone—This option makes your content public. Anyone can access and see it.
    • My Organization—If you are signed in with an organizational account, you see this option. This option allows your content to be shared with all authenticated users in the organization.
    • Groups—You can share your content with groups to which you belong and their members.

    Leave all options unchecked to set the sharing level to the owner of the item.

    If you are the owner of the existing map image layer, you can modify the group sharing settings.
  8. Optionally, click the Configuration tab and change settings.

    For more information, see Configure a map image layer.

  9. Optionally, click the Content tab to view the folder, new web layers, and sublayers with assigned IDs if available.

    If you enabled the Allow assignment of unique numeric IDs for sharing web layers option on the Map Properties dialog box, assigned IDs appear for each sublayer. To change an ID, click the number next to the layer or table. On the Layer Properties or Standalone Table Properties dialog box, on the General tab, type a custom integer ID in the Layer ID or Table ID text box. For more information, see Assign layer IDs.

  10. Under Finish Sharing, click Analyze Identify potential performance bottlenecks and errors to review for potential problems.

    Errors and warnings are listed on the Messages tab. Right-click a message to open its help topic or take corrective action in the software. Errors Error must be resolved before you can share your GIS resource. Resolving warnings Warning is recommended but not required.

    Learn more about analyzing GIS resources

  11. After you have resolved errors, and optionally, resolved warnings, click Publish Publish to share the web layer.

    To save a service definition for the web layer instead, click the Publish drop-down arrow and click Save As SD.


    Publishing a service definition staged to overwrite will automatically replace the existing web layer if found on the server. To avoid unintentionally overwriting existing web layers and their associated data, store these service definitions in a way that makes them distinguishable from other service definitions.

  12. When the web layer is successfully published, click the Manage the web layer link at the bottom of the pane to access the web layer in your portal.

    If the web layer will be drawn from cache built automatically on the server, the web layer may not be viewable while cache generation is in progress. Click Jobs Open Job Status Pane to view the cache status in the Job Status pane.

Cached map image layer considerations

When you overwrite a map image layer that is drawn using tiles from a cache (a cached map image layer), you can choose whether to keep the existing cache. If you keep the existing cache, you can change many configuration properties of the layer. For example, you can increase the visible range by publishing additional levels of detail at either end of the range. However, you can't decrease the visible range of the layer or change the tiling scheme, image format, compression, or cache directory.

Cache extent settings made when you shared the layer previously are not preserved. By default, when you overwrite the map image layer, the map extent is cached. Optionally, you can cache tiles for an area of interest. In either case, tiles are cached only for the levels of detail that you select on the Build Tiles and Calculate dialog box.

If you choose not to keep the existing cache, you can change all configuration properties of the service, including the tiling scheme and cache directory. Essentially, this is the same as sharing a new map image layer, except that the service URL does not change.

If you choose not to keep the existing cache, the tiles that were built for the previously shared map image layer are disassociated from the layer and new tiles are built. The old tiles are associated with an automatically generated web layer named <layer>_<timestamp>. (Essentially, it is maintained as a backup in case you have a further use for it.) You can delete this cache with the Delete Map Server Cache tool.

Keep the existing cache

Follow the steps below to access the Keep existing cache setting:

  1. At the top of the Overwrite Web Layer pane, click the Configuration tab.
  2. On the Configure Layers tab Configure Layers, click Configure Web Layer Properties Configure Web Layer Properties next to Map Image.
  3. Under Layer Drawing, check or uncheck the Keep existing cache box.

    If you do not keep the cache, all existing tiles are disassociated from your web layer and automatically associated with an archived web layer named <layer>_<timestamp>.


    If you overwrite a map image layer as an administrator, the archived web layer is stored in your portal content.

Related topics