Introduction
This article covers common issues encountered when running HashiCorp Nomad on macOS, specifically related to the Docker driver not being detected and job failures due to mount permission errors.
Problem
Users running Nomad on macOS may face challenges such as:
-
Nomad is not detecting the Docker driver when started in development or server/client mode.
-
Nomad jobs are failing with mount permission errors.
Prerequisites
This article applies to the following setup:
-
macOS (any version supporting Docker Desktop)
-
Docker Desktop is installed and running
-
HashiCorp Nomad
-
Docker driver usage in Nomad
Cause
These issues are typically caused by:
-
Docker Desktop configuration is not allowing the default Docker socket to be used.
-
The virtualization method in Docker Desktop (VirtioFS) is causing mount permission issues when Nomad attempts to create mount paths for allocations.
Overview of Possible Solutions
Below are potential solutions to address these issues on macOS.
Solutions
Solution 1: Enable Default Docker Socket in Docker Desktop
If Nomad cannot detect the Docker driver:
-
Open Docker Desktop.
-
Navigate to Settings → Advanced.
-
Check the box labeled "Allow the default Docker socket to be used (requires password)".
-
Click "Apply & Restart".
This enables Nomad to communicate with Docker over the expected socket.
Solution 2: Change Docker Virtualization Framework to gRPC FUSE
If Nomad jobs fail due to mount permission errors:
-
Open Docker Desktop.
-
Go to Settings → General.
-
Locate the "Virtualization framework" option.
-
Switch from VirtioFS to gRPC FUSE.
-
Restart Docker Desktop for the changes to take effect.
This workaround resolves known permission issues when Docker attempts to mount paths used by Nomad allocations.
Outcome
After applying the above solutions:
-
Nomad should successfully detect the Docker driver on macOS.
-
Nomad jobs should launch without mount-related permission errors.
If the issue persists, confirm that Docker Desktop is running the latest version and that the Nomad binary is correctly configured to use the Docker driver.