# Unraid "Docker service failed to start" — test log
Date: 2026-11-07, 12:09–12:18 UTC
Author: Nysa Dimitriou

## Method

Unraid's Docker storage is a filesystem inside a file (docker.img), loop-mounted at
/var/lib/docker. To reproduce the daemon's behaviour without touching a live array, the
same arrangement was built inside a privileged container: a file of 128–320 MiB, mkfs'd,
loop-mounted, and dockerd pointed at it with --data-root.

Host: Ubuntu 24.04.2 LTS, kernel 6.8.0-147-generic, Docker 27.5.1 client / 29.8.0 server.
Container: docker:29-dind image, --privileged, dockerd 29.9.3 inside.
Every dockerd below ran with: --iptables=false --ip6tables=false --bridge=none,
so no firewall rules were touched on the host.

The Unraid box this was written from, read out of its own mount table from inside a
container on it:

  /mnt/cache/system/docker/docker.img on / type btrfs (rw,noatime,ssd,discard=async,
    space_cache=v2,subvolid=4426,subvol=/btrfs/subvolumes/d8b93b28...)
  /dev/loop2      150G   31G  118G  21% /

## E1 — healthy baseline: 256 MiB ext4 image

  truncate -s 256M docker.img && mkfs.ext4 -q -F docker.img
  mount -o loop docker.img /mnt/img
  dockerd --data-root /mnt/img/docker ...

  /dev/loop29  229.9M  11.8M  201.3M   6% /mnt/img        (after pulling alpine:3.20)
  server=29.9.3
  docker pull alpine:3.20  -> exit 0
  docker run --rm alpine:3.20 sh -c 'echo container_ok' -> container_ok
  du -sh /mnt/img/docker   -> 11.5M

Note: mkfs.ext4 gives 229.9 MiB usable out of 256 MiB (5% reserve + metadata).

## E2 — ext4 image filled to 100%, daemon restarted

  dd if=/dev/zero of=/mnt/img/fill bs=1M     -> ENOSPC
  /dev/loop29  229.9M  225.9M  0  100% /mnt/img

  Daemon output:

  level=warning msg="failed check for fsverity support" error="mkdir /mnt/img/docker/containerd/daemon/io.containerd.content.v1.content/.fsverity-check-3476257241: no space left on device"
  level=info msg="Daemon shutdown complete" error="failed to start daemon: Unable to get the TempDir under /mnt/img/docker: mkdir /mnt/img/docker/tmp: no space left on device"
  failed to start daemon: Unable to get the TempDir under /mnt/img/docker: mkdir /mnt/img/docker/tmp: no space left on device

  Client, after the daemon exited:

  $ docker version
  server=
  Cannot connect to the Docker daemon at unix:///tmp/d.sock. Is the docker daemon running?
  $ docker pull busybox:1.36
  Cannot connect to the Docker daemon at unix:///tmp/d.sock. Is the docker daemon running?

## E3 — image that is not a filesystem (corrupt / zero length)

  128 MiB of /dev/urandom in docker.img, then:

  $ mount -t ext4 -o loop bad.img /mnt/bad          (util-linux mount, as on Unraid)
  mount: /mnt/bad: wrong fs type, bad option, bad superblock on /dev/loop29,
         missing codepage or helper program, or other error.
         dmesg(1) may have more information after failed mount system call.
  exit=32

  $ e2fsck -fn bad.img
  e2fsck 1.47.4 (6-Mar-2025)
  ext2fs_open2: Bad magic number in super-block
  e2fsck: Superblock invalid, trying backup blocks...
  e2fsck: Bad magic number in super-block while trying to open bad.img
  The superblock could not be read or does not describe a valid ext2/ext3/ext4

  Zero-length docker.img, same command:
  mount: mounting /dev/loop29 on /mnt/bad failed: Invalid argument      (busybox mount)
  Note: busybox prints EINVAL where util-linux prints the longer message.

## E4 — daemon.json refused at startup

  { "log-driver": "journald", }   (trailing comma)
  unable to configure the Docker daemon with file /tmp/cfg.json: invalid JSON:
  invalid character '}' looking for beginning of object key string

  { "bogus-key": true }
  unable to configure the Docker daemon with file /tmp/badkey.json: the following
  directives don't match any configuration option: bogus-key

  { "storage-driver": "btrfs" }   (on an ext4 data root)
  failed to start daemon: error initializing graphdriver: prerequisites for driver
  not satisfied (wrong filesystem?): btrfs

  Validation without starting the daemon:

  $ dockerd --validate --config-file /tmp/bad.json
  unable to configure the Docker daemon with file /tmp/bad.json: invalid JSON: ...
  exit=1
  $ dockerd --validate --config-file /tmp/good.json
  configuration OK
  exit=0

## E5 — daemon starts, every container fails

  daemon.json: { "log-driver": "notadriver" }

  daemon: level=info msg="API listen on /tmp/nd.sock"    server=29.9.3
  $ docker run --rm alpine:3.20 true
  docker: Error response from daemon: error looking up logging plugin notadriver:
  plugin "notadriver" not found

## E6 — btrfs image, 320 MiB, filled to 100%

  dd if=/dev/zero of=/mnt/b/fill ...   -> dd_exit=1
  /dev/loop29  320.0M  246.1M  8.0K  100% /mnt/b
  btrfs filesystem usage -T /mnt/b:
      Device size:        320.00MiB
      Device allocated:   319.00MiB
      Device unallocated:   1.00MiB

  Daemon restarted on the full image: level=info msg="API listen on /tmp/d2.sock",
  server=29.9.3 — it starts. Then:

  $ docker pull alpine:3.19
  3.19: Pulling from library/alpine
  17a39c0ba978: Pulling fs layer
  failed to copy: failed to send write: write /mnt/b2/docker/containerd/daemon/io.containerd.content.v1.content/ingest/7b1d82b15d3453912552aca21128e9458a7b5176870db630385fa2dd4721221a/data: no space left on device

  $ docker run --rm alpine:3.20 sh -c 'dd if=/dev/zero of=/x bs=1M count=3'
  docker: Error response from daemon: commit failed: write /mnt/b2/docker/containerd/daemon/io.containerd.snapshotter.v1.overlayfs/metadata.db: no space left on device

  daemon log:
  level=error msg="Handler for POST /containers/create returned error"
    error-response="commit failed: write .../metadata.db: no space left on device"
    method=POST request-url=/v1.56/containers/create status=500

## E7 — growing the image in place

  ext4, 128 MiB image holding 100.1 MiB, grown to 256 MiB while unmounted:
    df before: /dev/loop29  114.5M  100.1M  5.4M  95%
    umount; truncate -s 256M g2.img
    e2fsck -f -y g2.img      -> exit 0
    resize2fs g2.img         -> Resizing the filesystem on g2.img to 262144 (1k) blocks.
    df after:  /dev/loop29  233.9M  100.1M  117.0M  46%     data intact (100.0M)

  btrfs, 128 MiB image holding 52.9 MiB, grown to 256 MiB:
    df before: /dev/loop29  128.0M  52.9M  0  100%   <- btrfs df shows 0 free
    umount; truncate -s 256M h.img; mount again
    btrfs filesystem resize max /mnt/g -> Resize device id 1 (/dev/loop29) from 128.00MiB to max
    df after:  /dev/loop29  256.0M  52.9M  128.0M  29%
    btrfs filesystem usage: Device unallocated: 129.00MiB

## Things not tested

- Unraid's own UI wording and its Docker page. The strings above are the daemon's.
- A live Unraid array; every image here was 128-320 MiB, not tens of GB, so no timings.
- btrfs quotas, btrfs check on a corrupt btrfs image, and ZFS.
- Whether Unraid's own "resize vDisk" path does what truncate+resize2fs did here.