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.
fin vm restart
fin system resetand restart project containers with
fin project restart
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:
... (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.
yesto remove malfunctioned virtual machine.
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.
Sometimes docker-machine certificates re-generation fails. Perform the following steps to resolve:
fin vm restart
If above did not help, perform commands below and then reboot your host:
fin docker-machine regenerate-certs docksal -f fin vm restart
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
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/
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:
Run the following command:
fin docker-machine regenerate-certs -f --client-certs docksal fin vm restart
Verify the docksal machine starts and that you can start your projects.
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.
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.
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
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.
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.
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: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.
4433) or different/specific IPs (e.g.,
open /Users/John.Doe/.docker/machine/machines/docksal/config.json: permission denied
You created the Docksal VM as the root user (probably using
This is not recommended in particular because of the problems like this.
Re-create vm as a regular user
sudo fin vm remove fin system start
Error with pre-create check: "VirtualBox is configured with multiple host-only adapters with the same IP \"192.168.64.1\". Please remove one."
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
fin vm restartafter you apply your new DNS settings.
macOS DNS settings example:
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 files for configuration errors, fix them and run
fin project start (
fin start for short).
Please see a separate troubleshooting document on share creation, share mounting, and 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
cannot allocate memory for the buffer pool means you don’t have enough of free memory on your Docksal VM
to run the project.
See Issue 3. Lack of memory for resolution.
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.
Oracle America, Inc.
In certain cases you may have to reboot your Mac and then reinstall VirtualBox manually.
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.
See docker login documentation and to use docker client to either log out or relogin.
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
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.
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.
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.
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.
Grant Full Disk Access privileges to
/sbin/nfsdand click Go, then click Open
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.