Common Issues

Quite often a problem may reside within the 3rd party tools, project code, local configuration, etc., and not the stack. To make sure that the Docksal stack works properly, try launching any of the sample projects.
If you believe the issue is within the Docksal stack, then read on.

First, try these quick fix steps in the order listed below. Check if the issue has cleared out after each step.

  • Update Docksal to the latest version. See the updates section.
  • (Only if you use VirtualBox) Restart the Docksal VM: fin vm restart
  • Reset Docksal system services with fin system reset and restart project containers with fin project restart
  • Reboot the host (your computer or remote server)

If that did not help, take a look at some of the common problems using Docksal and ways to resolve them below.

If above did not help, try:

  • searching the GitHub issue queue. Others may have experienced a similar issue and already found a solution or a workaround.
  • asking community for support in our Gitter room
  • creating a new issue if your problem is still not resolved.

Issue 1. Failed Creating Docksal Virtual Machine on Windows

...
(docksal) Downloading C:\Users\alex\.docker\machine\cache\boot2docker.iso from https://github.com/boot2docker/boot2docker/releases/download/v17.04.0-ce/boot2docker.iso...
(docksal) 0%....10%....20%....30%....40%....50%....60%....70%....80%....90%....100%
(docksal) Creating VirtualBox VM...
(docksal) Creating SSH key...
Wrapper Docker Machine process exiting due to closed plugin server (read tcp 127.0.0.1:49393->127.0.0.1:49392: wsarecv: An existing connection was forcibly closed by the remote host.)
Error creating machine: Error in driver during machine creation: read tcp 127.0.0.1:49393->127.0.0.1:49392: wsarecv: An existing connection was forcibly closed by the remote host.
 ERROR:  Proper creation of virtual machine has failed
         For details please refer to the log above.
         It is recommended to remove malfunctioned virtual machine.
Remove docksal? [y/n]:

If you see this error, most likely you had just installed Virtual Box. Sometimes Virtual Box fails to initialize its network interfaces properly.

How to Resolve

  1. Reply yes to remove malfunctioned virtual machine.
  2. Reboot your local host and try again.

Issue 2. Error checking TLS Connection (VM is not accessible)

2a. Certificate validation, getsockopt connection refused:

Error checking TLS connection: Error checking and/or regenerating the certs: There was an error validating certificates for host "192.168.64.100:2376": dial tcp 192.168.64.100:2376: getsockopt: connection refused
You can attempt to regenerate them using 'docker-machine regenerate-certs [name]'.
Be advised that this will trigger a Docker daemon restart which will stop running containers.

How to Resolve

Sometimes docker-machine certificates re-generation fails. Perform the following steps to resolve:

  1. Perform fin vm restart
  2. If above did not help, then reboot your local host

  3. If above did not help, perform commands below and then reboot your host:

    fin docker-machine regenerate-certs docksal -f
fin vm restart

  4. In the rare cases when above did not help the only solution is to delete the existing VM and re-create it.

    fin vm remove
fin system start

2b. Certificate validation, x509 certificate has expired

Error checking TLS connection: Error checking and/or regenerating the certs: There was an error validating certificates for host "192.168.64.100:2376": x509: certificate has expired or is not yet valid
You can attempt to regenerate them using 'docker-machine regenerate-certs [name]'.
Be advised that this will trigger a Docker daemon restart which might stop running containers.

 ERROR:  Failed to properly access virtual machine
        In case you see certificates problem, try rebooting your local host.
        Common issues: https://docs.docksal.io/troubleshooting/common-issues/

How to Resolve

For reference: https://docs.docker.com/machine/reference/regenerate-certs/

If you see the above error where it mentions x509: certificate has expired or is not yet valid, then you need to regenerate your certificates with the added --client-certs argument to the regenerate command. Perform the following steps:

  1. Run the following command:

    fin docker-machine regenerate-certs -f --client-certs docksal
fin vm restart

  2. Verify the docksal machine starts and that you can start your projects.

Issue 3. Out-of-memory Issues

Composer on Drupal 8 projects might spawn this error:

The following exception is caused by a lack of memory and not having swap configured
Check https://getcomposer.org/doc/articles/troubleshooting.md#proc-open-fork-failed-errors for details

By default, a Docksal virtual machine is provisioned with 2GB (2048MB) of RAM. This should be enough for a decent size Drupal 8 project and composer.

How to resolve

  1. If the VM keeps running out of memory or you are getting weird issue with the db (or other) services failing, then try stopping all active projects (fin stop --all) and only start the one you need.

  2. Alternatively give the VM more RAM (e.g., 4096 MB). This may only be necessary when running several very heavy stacks/projects at the same time.

fin vm ram 4096

Issue 4. Conflicting NFS Exports (files are not accessible)

 ERROR:  conflicting exports for /Users, 192.168.64.100
exports:11: export option conflict for /Users
-----------------
/Users 192.168.64.100 -alldirs -mapall=0:0
# <ds-nfs docksal
/Users 192.168.64.100 -alldirs -mapall=501:20
# ds-nfs>

With NFS a single directory can only be exported once. It can not be exported several times with different settings.

How to Resolve

Remove the conflicting export from /etc/exports (remove the non-docksal one), save the file, and run fin vm restart or fin system start again.

Issue 5. Conflicting Ports

Resetting Docksal services...
 * proxy
docker: Error response from daemon: driver failed programming external connectivity
on endpoint docksal-vhost-proxy (a7addf7797e6b0aec8e3e810c11775eb77508c9079e375c083b3650df2dff9a2):
Error starting userland proxy: listen tcp 0.0.0.0:443: listen: address already in use.

This usually happens on Linux because the default Apache server bind to 0.0.0.0:80 and 0.0.0.0:443 (all IPs).
This prevents Docksal from running properly.

There can also be a port conflict if your computer has ever been configured to forward ports locally for development.

How to Resolve

  1. Stop Apache or
  2. Reconfigure Apache to listen on different ports (e.g., 8080 and 4433) or different/specific IPs (e.g., 127.0.0.1:80 and 127.0.0.1:443)

Issue 6. Config Permissions Issue (VM does not start)

open /Users/John.Doe/.docker/machine/machines/docksal/config.json: permission denied

You created the Docksal VM as the root user (probably using sudo). This is not recommended in particular because of the problems like this.

How to Resolve

Re-create vm as a regular user

sudo fin vm remove
fin system start

Issue 7. Multiple Host-only Adapters (VM is not created)

Error with pre-create check: "VirtualBox is configured with multiple host-only adapters with the same IP \"192.168.64.1\". Please remove one."

How to Resolve

  1. Open VirtualBox UI
  2. Open Preferences > Network tab
  3. Click “Host-only Networks” tab
  4. Click through adapters in list and delete the ones with the 192.168.64.1 IP

Issue 8. DNS Server Misbehaving

ERROR: error pulling image configuration: Get https://dseasb33srnrn.cloudfront.net/registry-v2/docker/registry/v2/blobs/sha256/9f/9fb8c0aed5fc7cc710884dc9cbd0974cc606053989b4f73f20e8b363e7d6cc7f/data?Expires=1490711517&Signature=SzvWOicPa6yZRxlBh1~vsl2xHtkOXR8xDj~usSP8aS9ZFhNQ8oH5pAcfZyx3sxgPgtqPgSOzuoaBtw5lT0~i0mpt~QCBpkgRhgyRQ8rzkbI1sG9ZRDXvRQ4sG49ckorbHyUT8isG5mEWl3Ar8kateU9he9fdlRhe5V5Zvn-et0s_&Key-Pair-Id=APKAJECH5M7VWIS5YZ6Q: dial tcp: lookup dseasb33srnrn.cloudfront.net on 10.0.2.3:53: server misbehaving

Pulling db (docksal/db:1.1-mysql-5.6)...
ERROR: Get https://registry-1.docker.io/v2/: dial tcp: lookup registry-1.docker.io on 10.0.2.3:53: server misbehaving

Your system DNS server does not properly resolve index.docker.io.

How to Resolve

Use Google Public DNS server or Open DNS.

  1. Please refer to the doc on how to apply DNS on your operating system.
  2. fin vm restart after you apply your new DNS settings.

macOS DNS settings example:

macOS DNS settings

Issue 9. FastCGI: Incomplete Headers

web_1        | [Wed Apr 19 14:57:37 2017] [error] [client 172.19.0.6] (111)Connection refused: FastCGI: failed to connect to server "/usr/lib/cgi-bin/php5-fcgi": connect() failed
web_1        | [Wed Apr 19 14:57:37 2017] [error] [client 172.19.0.6] FastCGI: incomplete headers (0 bytes) received from server "/usr/lib/cgi-bin/php5-fcgi"
web_1        | 172.19.0.6 - - [19/Apr/2017:14:57:37 +0000] "GET / HTTP/1.1" 500 639 "-" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36"

Errors like this appear when your Apache is misconfigured. Most often it happens because of misconfigured environment variables in docksal.yml. Sometimes it can be misconfiguration in .htaccess.

How to Resolve

Check docksal.yml and .htaccess files for configuration errors, fix them and run fin project start (fin start for short).

Issue 10. SMB Share Creation, Share Mounting, and Related Issues on Windows

Please see a separate troubleshooting document on share creation, share mounting, and related issues.

Issue 11. Common MySQL Related Issues

ERROR 2003 (HY000): Can't connect to MySQL server on 'db' (111)

There may be many different errors. Check Mysql logs with fin logs db for details. Here we will just look at the most common case.

If you see an error like:

db_1   | 170614 14:26:54 [Note] Plugin 'FEDERATED' is disabled.
db_1   | 170614 14:26:54 InnoDB: The InnoDB memory heap is disabled
db_1   | 170614 14:26:54 InnoDB: Mutexes and rw_locks use GCC atomic builtins
db_1   | 170614 14:26:54 InnoDB: Compressed tables use zlib 1.2.3
db_1   | 170614 14:26:54 InnoDB: Using Linux native AIO
db_1   | 170614 14:26:54 InnoDB: Initializing buffer pool, size = 256.0M
db_1   | InnoDB: mmap(274726912 bytes) failed; errno 12
db_1   | 170614 14:26:54 InnoDB: Completed initialization of buffer pool
db_1   | 170614 14:26:54 InnoDB: Fatal error: cannot allocate memory for the buffer pool
db_1   | 170614 14:26:54 [ERROR] Plugin 'InnoDB' init function returned error.
db_1   | 170614 14:26:54 [ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
db_1   | 170614 14:26:54 [ERROR] Unknown/unsupported storage engine: InnoDB
db_1   | 170614 14:26:54 [ERROR] Aborting
db_1   |
db_1   | 170614 14:26:54 [Note] mysqld: Shutdown complete

Then cannot allocate memory for the buffer pool means you don’t have enough of free memory on your Docksal VM to run the project.

How to Resolve

See Issue 3. Lack of memory for resolution.

Issue 12. VirtualBox Installation Fails on macOS High Sierra 10.13

New Docksal / VirtualBox installations fail on a fresh macOS High Sierra 10.13.x due to the new policy Apple introduced around third-party kernel extensions.

How to Resolve

  • Open System Preferences > Security & Privacy and click the Allow button for Oracle America, Inc.
  • Restart the VirtualBox installation manually

In certain cases you may have to reboot your Mac and then reinstall VirtualBox manually.

This video covers the manual steps necessary to install VirtualBox successfully. See detailed issue resolution.

Issue 13. Docker Unauthorized

docker: Error response from daemon: Get https://registry-1.docker.io/v2/docksal/ssh-agent/manifests/1.0: 
unauthorized: incorrect username or password.
See 'docker run --help'.

This means that you have docker credentials stored in docker config file, and those credentials are incorrect.

How to Resolve

See docker login documentation and to use docker client to either log out or relogin.

Issue 14. VirtualBox Installation Fails on Windows (Hyper-V Enabled)

Docksal / VirtualBox installations will fail on Windows if Hyper-V is enabled. This will result in a message similar to below:

Error with pre-create check: "This computer is running Hyper-V.
VirtualBox won't boot a 64bits VM when Hyper-V is activated.
Either use Hyper-V as a driver, or disable the Hyper-V hypervisor.
(To skip this check, use --virtualbox-no-vtx-check)

To Disable Hyper-V:

dism.exe /Online /Disable-Feature:Microsoft-Hyper-V /All

Issue 15. Firewall Blocking Access to Docksal

On Windows

Visiting the project URL in your browser results in a “site can’t be reached” message, could be the result of a local firewall application blocking access to Docksal’s canonical IP address.

Firewall configuration can also cause problems with SMB. See documentation on troubleshooting Windows SMB.

On Mac

If the containers do not mount properly during system start, you might see an error such as:

ERROR: for cli  Cannot create container for service cli: error while mounting volume with options: type='none' device='/Users/alex/Projects/myproject' o='bind': no such file or directory
ERROR: Encountered errors while bringing up the project.

How to Resolve

Configure your firewall to allow connections to and from 192.168.64.100 (Docksal’s canonical IP address used across all systems and configurations).

On macOS, go to System Preferences -> Security and Privacy -> Firewall and either turn the Firewall off completely or
configure it to allow all connections (see image). Then do fin system restart and check if it fixes the issue.

macOS firewall settings

Issue 16. NFS access issues on macOS

Your project’s codebase resides under one of the standard user folders in macOS (e.g., Downloads, Documents, Desktop) or on an external drive. Project stack does not start and displays an error such as:

ERROR:  The path is not accessible in Docker
        Could not access </path/to/project>
        It is not shared from your host to Docker or is restricted.

How to Resolve

Grant Full Disk Access privileges to /sbin/nfsd:

  • Open System Preferences
  • Go to Security & Privacy → Privacy → Full Disk Access
  • 🔒 Click the lock to make changes
  • Click +
  • Press ⌘ command + shift + G
  • Enter /sbin/nfsd and click Go, then click Open

macOS TCC nfsd

Alternatively, you can move the project’s codebase out of the restricted user folder (not helpful for external disks).

See blog post for more details.