Main Content

Troubleshoot WMS Servers

Connection Errors

One of the challenges of working with WMS is that sometimes you can have trouble connecting to a server.

Time-Out Error

A server may issue a time-out error such as:

Connection timed out: connect


Read timed out

Workaround: Try setting the 'TimeoutInSeconds' parameter to a larger value. The time-out setting defaults to 60 seconds. (The functions wmsread, wmsinfo, and wmsupdate all have 'TimeoutInSeconds' parameters.)

Server No Longer Provides Full WMS Services

The NASA Jet Propulsion Laboratory (JPL) server may issue the following error message:

This server no longer provides full WMS services!

The DataFed server,, cascades layers from the JPL server and may issue the following error message:

Error in Execution. Cannot fetch url.

Workaround: Use a TiledWMS URL or find a different server.

The JPL Global Imagery Service server,, is no longer providing full WMS services for any of the datasets. Any server (for example, that cascades data from this server is also affected by the change.

A small subset of the data can be accessed using a non-standard TiledWMS request. The available tiled patterns can be found at:

The WMS parameters must be in the exact order. If you wish to obtain a tile, you can prepend the prefix, '' in front of the request found in the CDATA section of the GetTileService request.

For example:

url = ['' ... 
'request=GetMap&layers=global_mosaic&srs=EPSG:4326&'  ... 
'format=image/jpeg&styles=visual&width=512&height=512&' ... 
[A, R] = wmsread(url);

Elevation layers from can be replaced with layers from the NASA WorldWind server ( The Blue Marble layer can be replaced with a Blue Marble layer from the NASA Goddard Space Flight Center WMS SVS Image Server ( or the Blue Marble: Next Generation layer from the NASA Earth Observations (NEO) WMS Server (

The Daily Planet layer can be replaced with the 'True Color (1 day - Terra/MODIS Rapid Response)' layer from the NASA Earth Observations (NEO) WMS server.

HTTP Response Code 500

In some cases, the server becomes temporarily unavailable or the WMS server application experiences some type of issue. The server issues an HTTP response code of 500, such as:

Server returned HTTP response code: 500 for URL: ...

Workaround: Try again later. Also try setting a different 'ImageFormat' parameter.

WMSServlet Removed

If the server issues an error such as:

WebMapServer cannot communicate to the host
The host is unknown.

This message indicates that the server it is trying to access is no longer available.

Workaround: Choose a different layer.

Wrong Scale

The server often throws this error message:

This layer is not visible for this scale. The maximum valid scale
is approximately X. Zoom in and try again if desired. The scale of 
the image requested is Y.

X and Y represent specific values that vary from layer to layer.

Workaround: Some of the WMS sources this server accesses have map layers sensitive to the requested scale. Zoom in (choose a smaller region of interest), or zoom out (choose a larger region of interest). Alternatively, you can select a larger output image size to view the layer at the appropriate scale.

Problems with Geographic Limits

Some servers do not follow the guidelines of the OGC® specification regarding latitude and longitude limits.

Latlim and Lonlim in Descending Order

The OGC specification requires, and the WMS functions expect, that the limits are ascending. Some sites, however, have descending limits. As a result, you may get this error message:

"??? Error using ==> WMSMapRequest>validateLimit at 1313
Expected the elements of 'Latlim' to be in ascending order." 

Workaround: To address this problem, set the Latlim and Lonlim properties of WMSLayer:

layer = wmsfind('', 'SearchField', 'serverurl');
layer = wmsupdate(layer);
latlim = [min(layer.Latlim), max(layer.Latlim)];
lonlim = [min(layer.Lonlim), max(layer.Lonlim)];
layer.Latlim = [max([ -90, latlim(1)]), min([ 90, latlim(2)])];
layer.Lonlim = [max([-180, lonlim(1)]), min([180, lonlim(2)])];
[A,R] = wmsread(layer);

Update your layer before setting the limits. Otherwise, wmsread updates the limits from the server, and you once again have descending limits.

Limits Exceed Bounds

Some servers have limits that exceed the bounds of [-180, 180] for longitude and [-90, 90] for latitude.

Workaround: To address this problem, follow the same procedure outlined in Latlim and Lonlim in Descending Order.

Problems with Server Changing LayerName

In most cases, the updated layer returned by wmsupdate should have ServerURL and LayerName properties that match those of the layer you enter as input. In some cases when the layer is updated from the server, the server returns a layer with a different LayerName, but the ServerURL and LayerTitle are the same. The layers from the server have names such as 'X:Y', where X and Y are ASCII numbers. Since the time of your last update, a layer has been added to or removed from the server causing a shift in the sequence of layers. Since the LayerName property is constructed with ASCII numbers based on the layer's position in this sequence, the LayerName property has changed. For layers from the server, wmsupdate matches the LayerTitle property rather than the LayerName property.

Non-EPSG:4326 Coordinate Reference Systems

Some layers are not defined in the EPSG:4326 or CRS:84 coordinate reference system. You cannot read these layers with the wmsread function.

Workaround: Use the WMSMapRequest object to construct a request URL and the WebMapServer.getMap method to read the layer. See Understanding Coordinate Reference System Codes and Retrieving Your Map with WebMapServer.getMap for more information.

Map Not Returned

Sometimes you can connect to the WMS server, but you do not receive the map you are expecting.

Blank Map Returned

A server may return a blank map.

Workaround: You can change the scale of your map; either increase the image height and width or change the geographic bounds. Another possibility is that your requested geographic extent lies outside the extent of the layer, in which case you should change the extent of your request. A third possibility is that you have the wrong image format selected; in this case, change the 'ImageFormat' parameter.

HTML File Returned

You may receive this error message:

The server returned an HTML file instead of an image file.

Workaround: Follow the directions in the error message. The following example, which uses a sample URL, illustrates the type of error message you receive.

% Example command.
[A,R] = wmsread(['',...

Sample error message:

Error using WebMapServer>issueReadGetMapError (line 974)
The server returned an HTML file instead of an image file. 
You may view the complete error message by issuing the command,
Error in WebMapServer>readImageFormat (line 874)
        issueReadGetMapError(filename, requestURL);

Error in WebMapServer>readGetMapFile (line 852)
    A = readImageFormat(filename, requestURL);

Error in WebMapServer/getMap (line 299)
            A = readGetMapFile(filename, h.RequestURL);

Error in wmsread (line 376)
A = server.getMap(mapRequestURL);

XML File Returned

The server issues a very long error message, beginning with the following phrase:

An error occurred while attempting to get the map from the server. 
The error returned is <?xml version="1.0" encoding="utf-8"?> ...

Workaround: This problem occurs because the server breaks with the requirements of the OGC standard and returns the XML capabilities document rather than the requested map. Choose a different layer or server.

Unsupported WMS Version

In rare cases, the server uses a different and unsupported WMS version. In this case, you receive an error message such as:

The WMS version, '1.2.0', listed in layer.Details.Version is not 
supported by the server. The supported versions are: '1.0.0' '1.1.0' 
'1.1.1' '1.3.0' .

Workaround: Choose a different server.

Other Unrecoverable Server Errors

The server issues an error indicating that no correction or workaround exists. These cases result in the following types of error messages:

Server redirected too many  times (20)

An error occurred while attempting to parse the XML capabilities 
document from the server.

Unexpected end of file from server

An error occurred while attempting to get the map from the server. 
The server returned a map containing no data.

See Also

| |

Related Topics