🚨 Filebeat Error Guide: 'add_docker_metadata: unable to connect to Docker daemon' — Fix Container Enrichment

Overview

Filebeat’s container-metadata processor cannot reach the Docker API, so it cannot enrich events with container names and labels and logs:

add_docker_metadata: unable to connect to Docker daemon: cannot connect to Docker endpoint: Get "http://unix.sock/v1.24/containers/json": dial unix /var/run/docker.sock: connect: no such file or directory

The add_docker_metadata processor queries the local Docker daemon to attach fields like container.id, container.name, and container.labels.* to each log line. To do that it needs to talk to the Docker socket (usually /var/run/docker.sock). When Filebeat runs in a container without that socket mounted, or lacks permission to read it, or the host uses containerd/CRI-O instead of Docker, the processor cannot connect. Events usually still ship — just without container metadata — but the repeated errors are noisy and the enrichment you configured is silently missing.

Symptoms

• Repeated add_docker_metadata: unable to connect to Docker daemon on startup and periodically after.
• Shipped documents lack container.name, container.image, and container.labels.* fields.
• Variants like dial unix /var/run/docker.sock: connect: no such file or directory or ... permission denied.
• The Filebeat container runs, reads logs, and ships them, but enrichment is absent.
• The node was migrated from Docker to containerd/CRI-O and the processor was never updated.

Common Root Causes

• Socket not mounted into the Filebeat container (/var/run/docker.sock missing inside the container).
• Permission denied — the Filebeat user is not in the docker group or the socket’s group is different in-container.
• No Docker at all — the host uses containerd or CRI-O, so there is no Docker socket to connect to.
• Wrong endpoint / host configured for the processor (host: "unix:///var/run/docker.sock" mismatch).
• Rootless or remapped Docker exposing the socket at a non-default path.

How to diagnose

Confirm whether a Docker socket even exists on the node and what runtime is in use:

ls -l /var/run/docker.sock
sudo systemctl is-active docker containerd
kubectl get nodes -o wide   # CONTAINER-RUNTIME column shows docker vs containerd

From inside the Filebeat container, check the socket is visible and readable:

docker exec -it filebeat ls -l /var/run/docker.sock
docker exec -it filebeat cat /usr/share/filebeat/filebeat.yml | grep -A3 add_docker_metadata

Look at how the processor is wired and whether the socket is bind-mounted:

docker inspect filebeat --format '{{ range .Mounts }}{{ .Source }} -> {{ .Destination }}{{"\n"}}{{ end }}'
journalctl -u filebeat -f | grep -i add_docker_metadata   # if running on the host

Fixes

Mount the socket (Docker hosts). The processor needs read access to the daemon socket:

# docker-compose.yml (sanitized)
services:
  filebeat:
    image: elastic/filebeat:8.14.0
    user: root
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro

Point the processor at the socket explicitly if it lives at a non-default path:

processors:
  - add_docker_metadata:
      host: "unix:///var/run/docker.sock"

Fix permissions when the socket is mounted but unreadable — run Filebeat as a user that can read it, or align the group. Prefer least privilege over blanket root where your policy allows.

Switch to Kubernetes metadata on containerd/CRI-O nodes. If there is no Docker daemon, add_docker_metadata will never connect; use add_kubernetes_metadata instead, which talks to the API server:

processors:
  - add_kubernetes_metadata:
      host: ${NODE_NAME}
      matchers:
        - logs_path:
            logs_path: "/var/log/containers/"

If you do not need container fields, remove the processor to stop the noise:

processors:
  # - add_docker_metadata:   # removed; runtime has no Docker socket

After the change, confirm enrichment appears and the error stops:

journalctl -u filebeat -f | grep -i add_docker_metadata
# then check a document has container.name / kubernetes.pod.name populated

What to watch out for

• Container logs usually still ship without the metadata, so this error is easy to ignore until a dashboard that filters on container.name comes up empty.
• Mounting docker.sock grants powerful access to the host’s Docker API — mount it read-only (:ro) and scope who can run that container.
• On modern Kubernetes the runtime is almost always containerd or CRI-O, not Docker; reach for add_kubernetes_metadata rather than fighting a nonexistent socket.
• Rootless Docker puts the socket under $XDG_RUNTIME_DIR/docker.sock; set the processor host to that path.
• Do not run Filebeat as root just to read the socket if your security policy forbids it — add it to the socket’s group instead.

Related

• Filebeat Error Guide: Error extracting container id
• Filebeat Error Guide: connection refused
• Filebeat Error Guide: creating runner from config

More container logging walkthroughs are in the Filebeat guides.