amir20/dozzle · error

failed to write agent address file

Error message

failed to write agent address file: %w

What it means

Returned by AgentCmd.Run when os.WriteFile fails to persist the bound agent address to /tmp/dozzle-agent.addr. Other local processes use this file to discover the agent's endpoint, so failing to write it aborts startup.

Solutions

1. Ensure /tmp is writable by the agent's process user (`touch /tmp/test`).
2. Run the container with a writable tmpfs: `--tmpfs /tmp:rw,size=64m`.
3. Free disk space if the filesystem is full.
4. Do not mount /tmp read-only for the agent container.
5. Run the agent in a filesystem mode that permits writing temp files.

Example fix

// before
docker run --read-only amir20/dozzle:latest agent
// after
docker run --read-only --tmpfs /tmp:rw,size=64m amir20/dozzle:latest agent

[ -w /tmp ] || { echo '/tmp not writable'; exit 1; }

if err := agentCmd.Run(args, embeddedCerts); err != nil {
  if strings.Contains(err.Error(), "failed to write agent address file") {
    log.Fatal().Err(err).Msg("make /tmp writable (e.g. docker --tmpfs /tmp:rw)")
  }
}

When it happens

Trigger: /tmp is not writable (read-only rootfs, hardened container, noexec/tmpfs with restricted perms); disk full; the path exists as a directory or is otherwise unwritable by the process user.

Common situations: Running the agent in a distroless/read-only container filesystem; running as a non-root user with a locked-down /tmp; disk-full conditions on small VMs.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• failed to parse certificate
• failed to connect to
• invalid agent endpoint
• EOF error while converting gRPC to error
• unknown error: with

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

Appendix: source

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

	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()

	// Create shared client service (single ContainerStore for both agent server and notifications)
	clientService := docker_support.NewDockerClientService(client, args.Filter)

	// Create notification manager using the shared client service
	const notificationConfigPath = "./data/notifications.yml"
	clients := []container_support.ClientService{clientService}
	notificationManager := notification.NewManager(
		notification.NewContainerLogListener(ctx, clients),
		notification.NewContainerStatsListener(ctx, clients),
		notification.NewContainerEventListener(ctx, clients),
	)

View on GitHub (pinned to d9463cbe21)