.. index::
   single: Errors

.. _errors:

***************************************************
 Errors
***************************************************


.. index::
   pair: Error; drawEPP(): EPPL7 support is not available

drawEPP(): EPPL7 support is not available
-------------------------------------------------------------------------------

Error displayed when not using EPPL7 data.

This is a confusing error for users who are not even trying to view EPPL7
layers (EPPL7 is a raster format). The full error displayed may appear as
follows:

::

   msDrawRaster(): Unrecognized or unsupported image format ...

   drawEPP(): EPPL7 support is not available. 
   
Explanation
...............................................................................

When MapServer tries to draw a layer, it will attempt to use all of the
drivers it knows about, and the EPPL7 driver is the very last driver it will
try. This means that if a layer fails to draw for any reason, you will see
this error message.

There are other possible instances when this error can appear however, here
are a few:

- the server is returning either a ServiceException (which MapServer does not
  yet detect and parse into a reasonable error message) or it is returning an
  image in an unrecognized format ... for instance it is returning a GIF image
  and MapServer is not built to support GIF images.
  
- WMS servers often advertise multiple image formats but don't respect them in
  the getmap request.


.. index::
   pair: Error; loadLayer(): Unknown identifier. Maximum number of classes reached

loadLayer(): Unknown identifier. Maximum number of classes reached
-------------------------------------------------------------------------------

Error displayed when attempting to draw a layer with a large number of classes.

This error states that MapServer has reached its limit for the maximum number
of classes for the layer. This maximum can be modified in the MapServer
source, and can then be re-compiled. *map.h* contains the default values, and
below are the defaults for MapServer 4.10 and 4.8:

::

  #define MS_MAXCLASSES 250
  #define MS_MAXSTYLES 5
  #define MS_MAXLAYERS 200

.. note::
    This limitation was corrected in MapServer 5.0 and should no longer be a 
    problem.

.. index::
   pair: Error; loadMapInternal(): Given map extent is invalid

loadMapInternal(): Given map extent is invalid
-------------------------------------------------------------------------------

When loading your mapfile or one of your layers, MapServer complains about an
invalid extent.

Beginning in MapServer 4.6, MapServer got more strict about LAYER and MAP
extents. If minx is greater than maxx, or miny is greater than maxy, this
error will be generated. Check your MAP's EXTENT, LAYER's EXTENT, or
wms_extent setting to make sure this is not the case. MapServer **always**
takes in extents in the form of:

::

  EXTENT minx miny maxx maxy
  
How to get a file's EXTENT values?
...............................................................................

The easiest way to get a vector file's EXTENT is to use the `ogrinfo`_
utility, that is part of the GDAL/OGR library (for raster files you would use
the `gdalinfo`_ utility). Windows users can download the `FWTools`_ package,
which includes all of the GDAL and OGR commandline utilities. `MS4W`_ also
includes the utilities (in *ms4w/tools/gdal-ogr-utils/*). Linux users will
probably already have the GDAL libraries, if not you can also use the
`FWTools` package.

.. _`FWTools`: http://fwtools.maptools.org/
.. _`MS4W`: http://www.ms4w.com
.. _`ogrinfo`: http://www.gdal.org/ogr/ogrinfo.html
.. _`gdalinfo`: http://www.gdal.org/gdalinfo.html

For example, here is the results of the ogrinfo command on a shapefile (notice
the "Extent" line):

::

  $ ogrinfo province.shp province -summary
    INFO: Open of `province.shp'
    using driver `ESRI Shapefile' successful.

    Layer name: province
    Geometry: Polygon
    Feature Count: 1071
    Extent: (-2340603.750000, -719746.062500) - (3009430.500000, 3836605.250000)
    Layer SRS WKT:
    (unknown)
    AREA: Real (16.0)
    PERIMETER: Real (16.0)
    PROVINCE_: Real (16.0)
    PROVINCE_I: Real (16.0)
    STATUS: String (64.0)
    NAME: String (64.0)
    NAME_E: String (64.0)
    NAME_F: String (64.0)
    REG_CODE: Real (16.0)
    POLY_FEATU: Real (16.0)
    ISLAND: String (64.0)
    ISLAND_E: String (64.0)
    ISLAND_F: String (64.0)
    YYY: Real (16.0)
    SIZE: Real (16.0)
    ANGLE: Real (16.0)
    
Ogrinfo gives the file's extent in the form of (minx, miny),(maxx, maxy),
therefore the EXTENT in a mapfile would be:

::

    EXTENT -2340603.750000 -719746.062500 3009430.500000 3836605.250000
  
.. note::
    The EXTENT in a mapfile must be in the same units 
    as the :ref:`MAP` -level :ref:`PROJECTION`.

.. index::
   pair: Error; msGetLabelSize(): Requested font not found

msGetLabelSize(): Requested font not found    
-------------------------------------------------------------------------------

Error displayed when attempting to display a specific font.

This message tells you that MapServer cannot find specified font.

::

   Make sure that the font is properly referenced in the FONTSET lookup file.

.. seealso::
    :ref:`FONTSET`

.. index::
   pair: Error; msLoadFontset(): Error opening fontset

msLoadFontset(): Error opening fontset
-------------------------------------------------------------------------------

Error when attempting to display a label.

This message tells you that MapServer cannot find the :ref:`FONTSET` specified
in the :ref:`mapfile`.

::

   The FONTSET path is relative to the mapfile location.

.. seealso::
    :ref:`FONTSET`

.. index::
   pair: Error; msLoadMap(): Failed to open map file

msLoadMap(): Failed to open map file
-------------------------------------------------------------------------------

Error displayed when trying to display map image.

The message tells you that MapServer cannot find map file or has
problems with the map file.  Verify that you have specified the
correct path to the mapfile.  Linux/Unix users should make sure that
the web user has access permissions to the mapfile path as well.
Verify that the map file using shp2img to make sure that the
syntax is correct.

The error message states where MapServer thinks the mapfile is:

::

   [MapServer Error]: msLoadMap(): (D:/ms4w/apps/blah/blah.map)
   Failed to open map file D:/ms4w/apps/blah/blah.map

.. index::
   pair: Error; msProcessProjection(): no options found in 'init' file

msProcessProjection(): no options found in 'init' file
-------------------------------------------------------------------------------

Error displayed when attempting to use a specific projection.

The message tells you that the projection you're trying to use isn't defined 
in the epsg file.  Open your epsg file in a text editor and search for
your projection to make sure that it exists.

On Windows, the default location of the epsg file is *c:\\proj\\nad*.  MS4W
users will find the epsg file in *\\ms4w\\proj\\nad*.

.. seealso::
    :ref:`PROJECTION` and http://spatialreference.org

.. index::
   pair: Error; msProcessProjection(): No such file or directory

msProcessProjection(): No such file or directory
-------------------------------------------------------------------------------

Error displayed when trying to refer to an epsg file.

The message tells you that MapServer cannot find the epsg file.  

On Windows, the default location of the epsg file is *c:\\proj\\nad*.  MS4W
users will find the epsg file in *\\ms4w\\proj\\nad*.

Linux/Unix users should be careful to **specify the correct case** when 
referring to the epsg file, since filenames are case sensitive on Linux/Unix.  
"init=epsg:4326" refers to the epsg filename, and therefore "init=EPSG:4326" 
will not work because it will be looking for an *EPSG* file in uppercase.

Setting the location of the epsg file
..............................................................................

There are a few options available if you need to set the epsg location:

1. Use a system variable ("environment variable" on windows) called
   "PROJ_LIB" and point it to your epsg directory.
   
2. Use the mapfile parameter CONFIG to force the location of the epsg
   file.  This parameter is specified at the MAP level
   
   .. seealso::
        :ref:`mapfile`
   
   .. code-block:: mapfile

        MAP 
            ...
            CONFIG "PROJ_LIB" "C:/somedir/proj/nad/"
            ...
        END

3. Set an environment variable through your web server.  Apache has a 
   SetEnv directive that can set environment variables.  Add something
   like the following to your Apache *httpd.conf* file:
   
   ::

      SetEnv PROJ_LIB C:/somedir/proj/nad/
   

.. index::
   pair: Error; msProcessProjection(): Projection library error.major axis or radius = 0 not given

msProcessProjection(): Projection library error.major axis or radius = 0 not given
-----------------------------------------------------------------------------------

Error displayed when attempting to specify projection parameters.

Since MapServer 4.0, you are required to specify the ellipsoid for the
projection.  Omitting this ellipsoid parameter in later MapServer 
versions will cause this error.


Valid Examples
..............................................................................

4.0 and newer:

.. code-block:: mapfile

      PROJECTION
        "proj=latlong"
        "ellps=WGS84"
      END
  

before MapServer 4.0:

.. code-block:: mapfile

      PROJECTION
        "proj=latlong"
      END

.. seealso::
    :ref:`PROJECTION` and http://spatialreference.org

.. index::
   pair: Error; msQueryByPoint: search returned no results

msQueryByPoint: search returned no results
-------------------------------------------------------------------------------

Why do I get the message "msQueryByPoint(): Search returned no
results. No matching record(s) found" when I query a feature known to
exists?

The query feature requires a TEMPLATE object in the CLASS object of
your LAYER definition. The value points to a html fragment using
MapServer template syntax.

Example MapFile fragment:

.. code-block:: mapfile

  LAYER
    NAME "Parcel9"
    TYPE POLYGON
    STATUS OFF
    DATA "Parcels/area09_parcels"
    CLASS
      STYLE
        OUTLINECOLOR 128 128 128
        COLOR 153 205 255
      END
      TEMPLATE "templates/Parcels/area09_parcels.html"
    END

    HEADER "templates/Parcels/area09_parcels_header.html"
    FOOTER "templates/Parcels/area09_parcels_footer.html"

  END

Example Template:

:: 

  <tr>
    <td>[lrn]</td>
    <td>[PIN]</td>
  </tr>

The [lrn] is a special keyword that indicates the resulting line
number which starts at 1. [PIN] is the name of a feature attribute.

.. index::
   pair: Error; msReturnPage(): Web application error. Malformed template name

msReturnPage(): Web application error. Malformed template name
-------------------------------------------------------------------------------

This error may occur if you try to access a template file with a file extension
that is not recognized by MapServer.  Valid file extensions for templates are:

::


    .gml    
    .html 
    .htm 
    .js    
    .kml
    .svg    
    .tmpl
    .wml         
    .xml 

This error may also occur when you are attempting to use a URL template for a
query. The issue is that URL templates are only allowed for query modes that
return only one result (e.g. query or itemquery)

You can only use a URL template for a query in mode=query or mode=itemquery.
If you try it with mode=nquery or mode=itemnquery, you will get the error:

::
    
    Content-type: text/html msReturnPage(): Web application error. Malformed template name

.. seealso::
    :ref:`cgi_controls`

.. index::
   pair: Error; msSaveImageGD(): Unable to access file

msSaveImageGD(): Unable to access file
-------------------------------------------------------------------------------

Error displayed when attempting to display map image.

This error is displayed if MapServer cannot display the map image.  There are
several things to check:

- IMAGEPATH and IMAGEURL parameters in mapfile are valid

- In CGI mode, any IMAGEPATH and IMAGEURL variables set in the init pages
  are valid
  
- Linux/Unix users should verify that the web user has permissions to
  write to the IMAGEPATH

.. index::
   pair: Error; msWMSLoadGetMapParams(): WMS server error

msWMSLoadGetMapParams(): WMS server error. Image Size out of range, WIDTH and HEIGHT must be between 1 and 2048 pixels
----------------------------------------------------------------------------------------------------------------------

Error that is returned / displayed when a user has requested a map
image (via WMS) that exceeds the maximum width or height that the
service allows.

To increase the maximum map width and height for the service, use the
MAXSIZE parameter of the :ref:`MAP` object.  Producing larger map
images requires more processing power and more memory, so take care.

.. index::
   pair: Error; Unable to load dll

Unable to load dll (MapScript)
-------------------------------------------------------------------------------

One of the dll-s could not be loaded that mapscript.dll depends on.

You can get this problem on Windows and in most cases it can be dedicated to a
missing or an unloadable shared library. The error message talks about
mapscript.dll but surely one or more of the dll-s are missing that libmap.dll
depends on. So firstly you might want to check for the dependencies of your
libmap.dll in your application directory. You can use the Visual Studio
Dependency Walker to accomplish this task. You can also use a file monitoring
tool (like SysInternal's filemon) to detect the dll-s that could not be
loaded. I propose to store all of the dll-s required by your application in
the application folder. If you can run the mapscript sample applications
properly your compilation might be correct and all of the dlls are available.

C#-specific information
..............................................................................

You may find that the mapscript C# interface behaves differently for the
desktop and the ASP.NET applications. Although you can run the drawmap sample
correctly you may encounter the dll loading problem with the ASP.NET
applications. When creating an ASP.NET project your application folder will be
'\Inetpub\wwwroot\[YourApp]\bin' by default. The host process of the
application will aspnet_wp.exe or w3wp.exe depending on your system. The
application will run under a different security context than the interactive
user (under the context of the ASPNET user by default). When placing the dll-s
outside of your application directory you should consider that the PATH
environment variable may differ between the interactive and the ASPNET user
and/or you may not have enough permission to access a dll outside of your
application folder.
