Troubleshoot your Atlas installation

If you have any issues while installing or running Atlas, the following troubleshooting strategies may help you diagnose and fix the problem.

Out-of-memory Docker errors

When developing locally with Atlas, you will sometimes get out-of-memory errors. Docker is conservative about garbage collection, meaning you will sometimes need to use the Docker prune command to clean up unused Docker assets. To learn more about how to use the prune command, visit the Docker documentation on pruning.

"No space left on device" errors

The Atlas installer setup command uses docker load. You need enough disk space in both /var/lib/docker and /tmp to run setup. We recommend at least 20 GB of space for both directories. If you receive the error message Error processing tar file(exit status 1): ... no space left on device, increase the disk space in either the /var/lib/docker or /tmp directories.

"Docker daemon is not running" errors

When the setup command is running, you might see the error: The Docker daemon is not running. Please start Docker before proceeding. If this occurs, reboot your instance with the command sudo reboot. Then you can run the setup command again.

View server logs

To view your Docker logs to diagnose issues, run the command docker-compose logs -f and pipe the output of this command into a new log file. The -f flag lets you follow the log output. To view other flag options for this command, see the docker-compose logs documentation.

Expired license error message

Your Account page will display the expiration date of your Atlas user license so that you know when to get the renewal process started.

If your Atlas license has expired, you will see an expiration error when you try to start Atlas. If you see this message, contact us to discuss renewing your Atlas license.

Cannot verify certificate

On certain older systems Mapbox's certificate issued by DigiCert is not recognized. You can download a certificate authority bundle and configure wget to trust the certificate by executing these commands:

$ mkdir ~/ca_certs
$ openssl s_client -showcerts -servername \
  -connect </dev/null > ~/ca_certs/mapbox.crt
$ echo ca_directory=~/ca_certs >> ~/.wgetrc

Submit feedback about Atlas

If you have any technical issues with installing or running Mapbox Atlas, send an email to with the following information:

  • Operating system name and version
  • What were you doing when you ran into the problem? What specific commands did you run or actions did you take?
  • What was the expected outcome?
  • What was the actual outcome?
  • Any relevant error logs in the browser console
  • Any relevant application error logs
Was this page helpful?