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 might issue a time-out error such as Connection timed out: connect or Read timed out.

Workaround: Try setting the 'TimeoutInSeconds' parameter of the wmsread, wmsinfo, or wmsupdate function to a larger value. The time-out setting defaults to 60 seconds.

Unavailable Server

A server might be temporarily unavailable or busy, or the WMS server application might experience an issue. In some cases, the server issues an HTTP response code of 500, such as:

Server returned HTTP response code: 500 for URL: http://xyz.com ...

Workarounds:

Try again later.
Try requesting a different image format by setting the 'ImageFormat' parameter.

Try connecting multiple times by using a while loop and try, catch block. For example, this code makes five attempts to get information about the USGS National Map Seamless server. If the connection fails after five attempts, then the code errors.

numberOfAttempts = 5;
attempt = 0;
info = [];
serverURL = "http://basemap.nationalmap.gov/ArcGIS/services/" + ...
    "USGSImageryOnly/MapServer/WMSServer?";
while(isempty(info))
    try
        info = wmsinfo(serverURL);
        orthoLayer = info.Layer(1);
    catch e 
        
        attempt = attempt + 1;
        if attempt > numberOfAttempts
            throw(e);
        else
            fprintf('Attempting to connect to server:\n"%s"\n', serverURL)
        end        
    end
end

Intermittent Internet Access

You have intermittent Internet access or you want to share WMS data with someone without Internet access.

Workaround: Reading data from WMS servers requires Internet access. However, once you read data from a server, you can save the data as a MAT or GeoTIFF file. Once you save the data, you can load it without reading it again from the server. For more information, see Create WMS Maps When Internet Access Is Intermittent.

Geographic Limits in Descending Order or Out of Bounds

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

The OGC specification requires, and the WMS functions expect, that the limits are ascending. However, some sites have descending limits. As a result, you might see an error such as:

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

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

Workaround: Set the Latlim and Lonlim properties of the WMSLayer object:

layers = wmsfind('bluemarbleng');
layer = wmsupdate(layers(1));
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);

You must update your layer before setting the limits. Otherwise, the wmsread function updates the limits from the server, and you once again have unsupported limits.

Non-EPSG:4326 Coordinate Reference Systems

Some layers are not defined in the EPSG:4326 or CRS:84 coordinate reference system. Reading these layers with the wmsread function is not supported.

Workaround: Construct a request URL by using the WMSMapRequest object and read the layer by using the getMap object function. For more information, see Read WMS Maps Using Different Coordinate Reference Systems.

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 might 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 might see 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(['https://www.mathworks.com?',...
'&BBOX=-180,-90,180,90&CRS=EPSG:4326&VERSION=1.1.1']);

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,
 web('https://www.mathworks.com?&BBOX=-180,-90,180,90&CRS=EPSG:4326&VERSION=1.1.1')
  or
 urlread('https://www.mathworks.com?&BBOX=-180,-90,180,90&CRS=EPSG:4326&VERSION=1.1.1').
 
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 this 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.