Troubleshooting

This page contains some known issues and workarounds (if available) organized by the host system type.

All Systems

• There are no man pages. They were removed in the base CentOS container used.
• If the tempo2 plugin throws a library not found error for libpgplot.so and libcfitsio.so.5, try modifying your LD_LIBRARY_PATH in the ~/.bashrc file to add the pgplot directory: LD_LIBRARY_PATH=/home/astrosoft/pgplot/:$LD_LIBRARY_PATH
• If your web browser can't connect to the Jupyter notebook server, you may already have one running. Check the output when you run the 'notebook' command for messages about port 8888 being already in use. It's probably easiest to shut down all the notebooks and try the notebook command again. By default, the container is only forwarding one port. If you want to run more notebooks, you have to recreate the container and add more ports.
  • You man also have a Jupyter notebook running on your host system using the same port. Simply change the target port to connect both.
• If you get messages about the kernel dying when running Jupyter notebooks, you may want to try increasing the amount of memory allocated to the container. See the instructions on Managing Container Resources.

macOS & Windows

• If GUI windows are not appearing and Tcl/Tk is throwing errors indicating it cannot connect to the display, xhost may be blocking the connection attempt. To correct this, try the following steps:
  • In the host machine, run ipconfig.
  • Note the IP address for the Docker network adapter.
  • Still in the host machine, run xhost + <DOCKER IP> where <DOCKER IP> is replaced with the IP address noted above.
  • In the container, make sure that the DISPLAY environment variable is set to <DOCKER IP>:0.0 where <DOCKER IP> is replaced with the IP address noted above.
  • Run the GUI program.
  • If the problem persists, the nuclear option is to run xhost + in a terminal in the host machine. This will disable X server access controls and will allow any client to connect. This is not recommended unless the above instructions don't work since it makes the machine less secure.

macOS

• X Windows forwarding does not work properly in XQuartz 2.7.9. This is a known bug that was fixed in subsequent versions, so as a first step users should update their version to 2.7.11 or higher. If you need to remain on 2.7.9, this patch will fix the issue:
  • As root, edit the file /opt/X11/bin/startx.
  • insert after line 107:else defaultserverargs="$defaultserverargs -listen tcp"
  • Save the file and exit.
  • Kill XQuartz.
  • Run xhost + 127.0.0.1 in the terminal.
  • Create a new container and launch an X window, like xclock.
• Launching external GUIs (e.g. ds9) may fail with an error like: "No protocol specified. application-specific initialization failed: couldn't connect to display".
  • This may be solved by modifying the ~/.bash_profile on your host OS by adding the following line: "export DISPLAY=localhost:0"
  • You should then 1) source your modified ~/.bash_profile and 2) create a new container to make sure your changes take effect.
  • Occasionally & without warning, ds9 etc. windows may suddenly fail to load even after inputing the above fix. If this happens, simply create a new container.
  • If want to use the separate 'exec' terminal, you may need to set the $DISPLAY variable manually. *To do this, type 'echo $DISPLAY' in the main window of your active container, which should report back with something like "host.docker.internal:0".
    • Next, set the variable in your 'exec' window with the command "export DISPLAY=host.docker.internal:0"

Windows

• If you can't access the Jupyter notebook via the token generated by the NotebookApp:
  • Open a Windows Powershell terminal and run ipconfig. Note the IP address under the heading Ethernet adapter vEthernet (DockerNAT). You can also do this when calling the notebook by using the ip flag in the call (i.e. notebook --ip <Your.DockerNAT.IP.Address>)
  • Change the IP address in front of port 8888 in the token string (should be 0.0.0.0) to the IP address determined above. Reload the page and the Notebook should appear.
• If you are using the Docker terminal to interact with the container, you will not be able to pass the ^Z signal (control-z) to suspend the Jupyter Notebook. To run it in the background, use the command notebook &. To retrieve your cursor, hit enter.
• If the container is having problems forwarding X11 windows to the WSL instance set your DISPLAY variable in WSL to export DISPLAY=:0 and recreate the container