Common issues & solutions

Hint

If you find any issues that you cannot solve, please get in touch through our help pages!

General solutions

Update PlanetMapper to make sure you are running the latest version. It is possible that your bug may have been fixed in a recent update (you can also check the release notes for each version on GitHub).

Installation issues

PlanetMapper requires a minimum Python version of 3.10, so if you get ERROR: No matching distribution found for planetmapper when trying to install PlanetMapper, it is likely that your python version is too old. You can check your Python version by running python3 --version in a terminal.

`ContentTooShortError` when downloading SPICE kernels

If you get a ContentTooShortError when trying to download SPICE kernels, it is likely that the download was interrupted before the file was fully downloaded (e.g. due to an unstable network connection). You can try re-downloading the kernel by running the download command again, or you can manually download the kernel from the NAIF database and place it in the correct directory.

SPICE Errors

If you have any errors caused reported by the SPICE system, it is likely that it doesn’t have the correct SPICE kernels loaded. Therefore, make sure you have the appropriate SPICE kernels downloaded to your computer and that you have set the kernel directory correctly.

`SpiceNOLEAPSECONDS` Error

This error usually occurs when SPICE has not loaded any of your desired kernels. This may be because PlanetMapper is not looking in the correct directory for your kernels, so make sure you have set the kernel directory correctly.

`SpiceSPKINSUFFDATA` Error

This error usually occurs when SPICE has successfully loaded some kernels, but is missing ephemeris data for either the target body or the observer body. This may be because you have not downloaded the appropriate kernel containing the ephemeris data for this body.

The error message should tell you which body is missing, and you can then identify the correct kernel to download by searching the NAIF database. For example, if you are missing data for a planetary body, you can search the generic_kernels/spk/satellites/aa_summaries.txt file to identify which kernel need downloading.

`NotFoundError` Error

This error usually occurs when SPICE does not know the name of the body you are trying to observe, so may be caused by a typo.

Some small body kernels generated by JPL horizons only contain the numeric ID codes for the body, so you may need to try using the numeric ID instead of the name (e.g. use 399 instead of 'earth'). Alternatively, you could also manually create an additional text kernel file to map the name of the body to its numeric ID.

`SpiceKERNELVARNOTFOUND` Error

This error occurs when SPICE tries to load a variable (e.g. defining a body’s radii) that has not been defined in any kernels - this often happens with small body kernels generated by JPL horizons. To fix this, you can manually create an additional text kernel file containing the missing variables.

`SpiceNOFRAME` Error

This error occurs when SPICE tries to load a reference frame that has not been defined in any kernels. To fix this, you can manually create an additional text kernel file containing the missing reference frame definitions. PlanetMapper defaults to using the IAU reference frames for the target bodies (e.g. IAU_JUPITER for Jupiter), so if your target frame has a different name, you will need to explicitly specify it when creating planetmapper.Body objects:

body = planetmapper.Body('jupiter', frame='CUSTOM_JUPITER_FRAME')

Planets appear in the wrong position

This is likely to be due to an issue with your SPICE kernels or settings, possible fixes include…

Make sure you are using the correct observer - e.g. a planet will appear in a different position from Earth and from JWST.
Make sure you are using the correct observation time - times in PlanetMapper default to UTC, so make sure there are no time zone conversions needed.
Make sure you have the latest version of any SPICE kernels, especially for any observers like HST or JWST which have have locations which are difficult to predict accurately.
Make sure you are using the correct aberration correction.
If you are using WCS information saved in the FITS header to automatically set the disc position, note that telescope pointing information (i.e. the WCS information) is never perfect. For example, due to the errors in guide star tracking, JWST pointing is only accurate to ~0.5”.

PlanetMapper crashes when running graphical user interface over SSH

Recent versions of XQuartz appear to have a font handling bug which can cause PlanetMapper to crash when running the user interface over an SSH connection using X11 forwarding:

X Error of failed request:  BadValue (integer parameter out of range for operation)
  Major opcode of failed request:  45 (X_OpenFont)
  Value in failed request:  0x60027c
  Serial number of failed request:  3572
  Current serial number in output stream:  3573

As a temporary workaround, you can set the PLANETMAPPER_USE_X11_FONT_BUGFIX environment variable to true on your remote machine before running PlanetMapper if you experience this issue. You can add the following line to to your .bash_profile file to automatically set this environment variable:

export PLANETMAPPER_USE_X11_FONT_BUGFIX=true

This tells the PlanetMapper user interface to replace certain characters with ASCII equivalents (e.g. ↑ is replaced with ^) which seems to prevent the use of the fonts which cause XQuartz to crash. Note that this will make the user interface slightly more ugly, but should not affect functionality. If you are still having issues after trying this workaround, you can add a comment to the GitHub issue.

Wireframe plots appear warped or distorted

This is most likely to occur when using planetmapper.Body.plot_wireframe_radec() for a target located near the celestial pole (i.e. the target’s declination is near 90° or -90°). The plot can be distorted because spherical coordinates (like RA/Dec) are fundamentally impossible to represent perfectly in a 2D cartesian plot, with the distortion increasing at high declinations near the coordinate singularity at the celestial poles.

To fix this, you can use the planetmapper.Body.plot_wireframe_angular(), which by default uses a coordinate system centred on the target body, which minimises any distortion. The origin of the angular coordinate system can also be customised to be any point in the sky, for example, using body.plot_wireframe_angular(origin_ra=0, origin_dec=90) may be useful for plotting observations in the sky around the north celestial pole.

Plots may also appear distorted if using planetmapper.Body.plot_wireframe_angular() with a a custom origin that is a large distance from the target body.

RA/Dec wireframe plots appear split into two halves

If the target body is near RA=0°, the wireframe plot may appear to be split into two halves, due to part of the body having RA values near 0° and part having RA values near 360°. This can be fixed by using body.plot_wireframe_radec(use_shifted_meridian=True), which will plot the wireframe with RA coordinates between -180° and 180°, rather than the default of 0° to 360°.