amir20/dozzle · error

failed to create docker client

Error message

failed to create docker client: %w

What it means

Returned by AgentCmd.Run when docker.NewLocalClient fails to create a Docker API client for the local daemon. This wraps the underlying error (socket connection, TLS config, or API version negotiation failure). The agent cannot function without talking to the local Docker daemon, so startup aborts.

Solutions

1. Verify the Docker daemon is running: `docker info` on the host.
2. Inside a container, mount the socket: `-v /var/run/docker.sock:/var/run/docker.sock`.
3. Check DOCKER_HOST is unset or points to a valid endpoint (unix:///var/run/docker.sock or tcp://host:2375).
4. If using tcp://, enable the daemon's TCP listener and confirm firewall access.
5. Check user permissions for the docker socket (add user to docker group).

Example fix

// before (docker-compose)
services:
  agent:
    image: amir20/dozzle:latest
    command: agent
// after
services:
  agent:
    image: amir20/dozzle:latest
    command: agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

if ! docker info >/dev/null 2>&1; then echo 'Docker daemon unreachable'; exit 1; fi

if err := agentCmd.Run(args, embeddedCerts); err != nil {
  var netErr net.Error
  if errors.As(err, &netErr) { /* daemon/socket unreachable */ }
  log.Fatal().Err(err).Msg("agent startup failed: docker client")
}

When it happens

Trigger: Running `dozzle agent` when DOCKER_HOST points at an unreachable host, the Docker socket is missing or permission-denied, or the daemon is not running. Also fires when API version negotiation with the daemon fails.

Common situations: Agent started inside a container without mounting /var/run/docker.sock; Docker Desktop not running on the host; DOCKER_HOST set to a stale tcp:// endpoint; user lacks docker group membership.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• unknown error: with
• docker daemon unreachable or unsupported
• failed to start notification manager
• container not found
• registry requires authentication

AI-assisted analysis of amir20/dozzle@d9463cbe21 (2026-09-07). Data as JSON: /api/errors/82ddb3d66f946b8f. Report an issue: GitHub.

Appendix: source

Thrown at internal/support/cli/agent_command.go:147

func (h *persistingNotificationHandler) ClearCloudDispatcher() {
	h.manager.ClearCloudDispatcher()
	h.cloudConfig.Store(nil)
	if h.onCloudSet != nil {
		h.onCloudSet()
	}
	if err := os.Remove("./data/cloud.yml"); err != nil && !os.IsNotExist(err) {
		log.Error().Err(err).Msg("Could not remove cloud.yml on agent")
	}
}

func (a *AgentCmd) Run(args Args, embeddedCerts embed.FS) error {
	if args.Mode != "server" {
		return fmt.Errorf("agent command is only available in server mode")
	}
	client, err := docker.NewLocalClient(args.Hostname)
	if err != nil {
		return fmt.Errorf("failed to create docker client: %w", err)
	}
	certs, err := ReadCertificates(embeddedCerts, args.CertPath, args.KeyPath)
	if err != nil {
		return fmt.Errorf("failed to read certificates: %w", err)
	}

	listener, err := net.Listen("tcp", args.Agent.Addr)
	if err != nil {
		return fmt.Errorf("failed to listen: %w", err)
	}
	const agentAddrFile = "/tmp/dozzle-agent.addr"
	if err := os.WriteFile(agentAddrFile, []byte(args.Agent.Addr), 0644); err != nil {
		return fmt.Errorf("failed to write agent address file: %w", err)
	}
	go StartEvent(args, "", client, "agent")

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

View on GitHub (pinned to d9463cbe21)