Error Initializing the GDAL path variables

There is a rare issue that causes this error when a user launches HEC-RAS Mapper.

You may also see an error message when trying to run an analysis without having opened RAS Mapper.

Theses error messages imply that one of our core libraries, GDAL or HDF5, failed to initialize their necessary libraries. This is most likely because an older version of one of their dependencies is sitting in a bad spot on your system. 

Windows tightly controls library (DLL) search order, since this can be a common vector for computer viruses. The order is listed here.

Most other software doesn't suffer these issues because they put all of their necessary libraries in a single directory. Windows looks in the local directory first, and everyone is happy. HEC-RAS has to do something a little less common, since we're dealing with a mixture of modern and legacy code. To get parts of HEC-RAS to work in 32 and 64-bit, we need separate directories for the different versions of otherwise identical files. As is standard in these situations, we have a bin32 and bin64 folder beneath the main RAS install, and a bin32/bin64 folder beneath our GDAL folder. To force the correct files to be loaded, we add the appropriate 32/64 bit directory the PATH environment variable. This is done at runtime, only for the running RAS process, so it doesn't negatively affect anything else running on your system.

Unfortunately, adding those directories to the PATH is the 6th search area, and pre-empted by (2) and (4). We have found that some programs inappropriately place their installed DLLs directly into one of these directories. This prevents anyone else on the system from using a different (newer) version of that code. There are many libraries for unzipping, file storage, database management, etc. that are commonly used across the industry. If some rogue piece of software put an older version of these files in the system area during installation, HEC-RAS is forced to load the incompatible version of this code.

Fixes

To fix this issue, you should uninstall the incompatible software and inform that developer. Unfortunately, it's hard to know which software is responsible. There are some diagnostics that can help, most of which require administrator rights on the local machine.

The directories we are concerned with are

  • C:\Windows
  • C:\Windows\System32
  • C:\Windows\SysWOW64

The possible file conflicts are subject to change, but if you navigate to the main RAS install directory, look for files in $RAS/bin32, $RAS/bin64, $RAS/GDAL/bin32, $RAS/GDAL/bin64. (Screenshot of current dependencies shown below).

If any of these files are in the system directories listed above, that will likely cause a conflict with some HEC-RAS processes.