Docker Service Startup Failure When Using A Custom Docker Directory on Linux

On Linux, you can change where Docker persists its resources from /var/lib/docker to a different directory. This directory contains all of your images, container layers, and volumes, and if your boot volume is small, Docker can quickly dominate the disk.

Most references I’ve seen tell you to update the location by editing the /lib/systemd/system/docker.service configuration file and change the following line:

ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

…by adding an entry with the -g or --graph flag:

ExecStart=/usr/bin/dockerd -g /docker -H fd:// --containerd=/run/containerd/containerd.sock

Indeed, that works for versions before 17.05. However, in versions 17.05 and later, the -g and --graph options are deprecated. After updating Docker and restarting the service or host, you’ll see this error:

# systemctl start docker
Job for docker.service failed because the control process exited with error code. See "systemctl status docker.service" and "journalctl -xe" for details.

Checking the status of the service shows:

# systemctl status docker.service
● docker.service - Docker Application Container Engine
   Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
   Active: failed (Result: start-limit) since Sat 2023-03-25 14:17:09 GMT; 997ms ago
     Docs: https://docs.docker.com
  Process: 1701 ExecStart=/usr/bin/dockerd -g /docker/.docker -H fd:// --containerd=/run/containerd/containerd.sock (code=exited, status=1/FAILURE)
 Main PID: 1701 (code=exited, status=1/FAILURE)

Mar 25 14:17:07 docker systemd[1]: Failed to start Docker Application Container Engine.
Mar 25 14:17:07 docker systemd[1]: Unit docker.service entered failed state.
Mar 25 14:17:07 docker systemd[1]: docker.service failed.
Mar 25 14:17:09 docker systemd[1]: docker.service holdoff time over, scheduling restart.
Mar 25 14:17:09 docker systemd[1]: Stopped Docker Application Container Engine.
Mar 25 14:17:09 docker systemd[1]: start request repeated too quickly for docker.service
Mar 25 14:17:09 docker systemd[1]: Failed to start Docker Application Container Engine.
Mar 25 14:17:09 docker systemd[1]: Unit docker.service entered failed state.
Mar 25 14:17:09 docker systemd[1]: docker.service failed.

Or:

# systemctl status docker.service
● docker.service - Docker Application Container Engine
   Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
   Active: inactive (dead) since Sat 2023-03-25 14:28:01 GMT; 42s ago
     Docs: https://docs.docker.com
  Process: 5168 ExecStart=/usr/bin/dockerd -g /docker/.docker -H fd:// --containerd=/run/containerd/containerd.sock (code=exited, status=1/FAILURE)
 Main PID: 5168 (code=exited, status=1/FAILURE)

Mar 25 14:27:59 docker systemd[1]: Failed to start Docker Application Container Engine.
Mar 25 14:27:59 docker systemd[1]: Unit docker.service entered failed state.
Mar 25 14:27:59 docker systemd[1]: docker.service failed.
Mar 25 14:28:01 docker systemd[1]: docker.service holdoff time over, scheduling restart.
Mar 25 14:28:01 docker systemd[1]: Stopped Docker Application Container Engine.
Mar 25 14:28:01 docker systemd[1]: start request repeated too quickly for docker.service
Mar 25 14:28:01 docker systemd[1]: Failed to start Docker Application Container Engine.
Mar 25 14:28:01 docker systemd[1]: Unit docker.service entered failed state.
Mar 25 14:28:01 docker systemd[1]: docker.service failed.

Or:

# systemctl status docker.service
● docker.service - Docker Application Container Engine
   Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
   Active: activating (auto-restart) (Result: exit-code) since Sat 2023-03-25 14:28:56 GMT; 1s ago
     Docs: https://docs.docker.com
  Process: 5467 ExecStart=/usr/bin/dockerd -g /docker/.docker -H fd:// --containerd=/run/containerd/containerd.sock (code=exited, status=1/FAILURE)
 Main PID: 5467 (code=exited, status=1/FAILURE)

Mar 25 14:28:56 docker systemd[1]: Failed to start Docker Application Container Engine.
Mar 25 14:28:56 docker systemd[1]: Unit docker.service entered failed state.
Mar 25 14:28:56 docker systemd[1]: docker.service failed.

The status output will lead you to the cause. Check journalctl -xe and within a few lines you’ll see a message indicating that use of the —-graph flag is deprecated and to instead use —-data-root:

# journalctl -xe
<snip>
-- Unit docker.service has begun starting up.
Mar 25 14:28:58 docker dockerd[5480]: Flag --graph has been deprecated, Use --data-root instead
Mar 25 14:28:58 docker dockerd[5480]: the "graph" config file option is deprecated; use "data-root" instead
Mar 25 14:28:58 docker systemd[1]: docker.service: main process exited, code=exited, status=1/FAILURE
Mar 25 14:28:58 docker systemd[1]: Failed to start Docker Application Container Engine.

After changing the entry in /lib/systemd/system/docker.service to use the proper flag, Docker once again recognizes the non-default directory and starts normally.

ExecStart=/usr/bin/dockerd --data-root /docker -H fd:// --containerd=/run/containerd/containerd.sock