TroubleShooting - Maproom/qmapshack GitHub Wiki

Prev (OpenSource, Donation, etc) | Home | Manual | Index | (Reporting a bug) Next

Table of contents

Troubleshooting

Troubleshooting

Since the 13-Oct-2015 development version, you can start QMapShack with the commandline option "-f". Then a logfile org.qlandkarte.QMapShack.log will be created in the system's temporary folder. On a Windows installation, this temporary folder is C:\Users\your_user_name\AppData\Local\Temp. This logfile may give additional insight into the root cause of the trouble.

More details about restarting QMS after a data or configuration error are given in section "What to do if QMS doesn't start".

Create a backtrace of a crash on Linux

If QMapShack crashes on Linux the best you can do to help development is to send a backtrace. A backtrace is a log of the last code lines executed before the crash. Usually, this contains enough hints to fix the problem fast.

To create a backtrace you have to compile QMapShack as debug version yourself. Have a look at the getting started chapter of the wiki for basic instructions.

When you do the step:

ccmake ../QMapShack

Change the variable CMAKE_BUILD_TYPE to Debug. Now start the build process with

make

No need to do a "make install". To create a backtrace you have to start QMapShack with the GDB debugger:

gdb bin/qmapshack

At gdb's commandline prompt enter 'r' to run QMapShack. Now you can provoke the crash. After the crash enter 'bt' on gdb's commandline. This will output the backtrace. Copy the lines and attach them to your bug report.

Limitations of QMapShack for Windows, short: QMS

To limit the build and maintenance effort, the Windows binary packages for QMS come with a restricted set of 3rd party libraries. In particular, the timely maintenance of security-related libraries would either put an unmanageable burden on your QMS Windows maintainer or add an incalculable risk to the users (imagine what could happen if I package an SSL library where severe bugs such as Heartbleed are not yet fixed). Due to this limitation certain kinds of maps - in particular online maps - will not work.

Below those restrictions are summarized and possible workarounds are described. Please be aware that those workarounds are on the sole risk of the users - I cannot take responsibility in which situations they work or not.

Qt comes without SSL support

Qt5 binaries are delivered without SSL support due to legal restrictions in some countries. See qt-5-ssl. This may hinder some kinds of web maps (TMS, WMTS) to be downloaded properly. As a workaround, you could download a compatible Windows SSL package and copy the 2 DLLs libeay32.dll and ssleay32.dll to QMS home directory. The DLLs from the following 2 sources have been reported to work: indy (download latest file openssl-x.y.z-x64_86-win64.zip) or gisinternals. Please judge by yourself whether those sources are trustable for you and whether they fit your actual installation.

GDAL comes without curl support

The default GDAL libraries come without curl support. This may hinder some kinds of web maps to be downloaded properly. As a workaround, you could download GDAL binaries from gisinternals and then brute-force-copy the complete "bin" subdirectory including subdirectories to the QMS home directory.

GDAL comes without support for exotic formats

Some raster map formats (e.g. wavelet-based) are not supported by the default GDAL installation. The reasons may be various (licenses, dependencies, ...). A possible workaround is the same as adding curl support: use the GDAL binaries from gisinternals.

Proposals for extending the standard GDAL distribution for Windows with some additional plugins that support more raster map formats can be found on the "Tips & tricks for raster maps" page.

Limitations of QMapShack for MacOS

Launching the app will display a pop-up window saying the app is damaged

Beginning with Ventura 13 and Monterey Version 12.6.2 Apple has removed the option to launch apps downloaded from the internet. Instead, apps launched from the internet now show a somehow "obscured" alert. Previously, one can go to the settings of "Privacy and Security" to allow "Gatekeeper" to launch apps from the internet.

It is still possible to get the previous behavior by following the instructions described on "How to Allow Apps to be Downloaded & Opened from Anywhere on MacOS Ventura"

Essentially, you first need to run sudo spctl --master-disable in the terminal. You will get then the option to download from Anywhere in the System settings -> Security & Privacy -> General. Allow the Option to download from Anywhere. Then you can download QMS and confirm the pop-up coming up on launch. This way, you TRUST the source. You can also do a sudo spctl --master-enable to reverse to Apple standard.

curl SSL certificate problem

QMS is using curl supplied by Apple. If you will get a "curl: (60) SSL certificate problem: certificate has expired", the following steps are recommended:

Download certificate: curl -k https://curl.se/ca/cacert.pem -o ~/.cacert.pem
Export it
- in your bash profile: echo 'export CURL_CA_BUNDLE=~/.cacert.pem' >> ~/.bash_profile or
- in your zsh profile: echo 'export CURL_CA_BUNDLE=~/.cacert.pem' >> ~/.zprofile

Reload your shell, or source ~/.bash_profile resp source ~/.zprofile