amir20/dozzle · error

failed to start notification manager

Error message

failed to start notification manager: %w

What it means

Returned by AgentCmd.Run when notificationManager.Start() fails. The manager wires log/stats/event listeners against the Docker client service before the gRPC server comes up, so a failure here means the notification subsystem cannot be initialized and agent startup aborts.

Solutions

1. Check agent logs for the wrapped underlying error (%w detail) to identify the failing listener.
2. Verify the Docker daemon is healthy: `docker events` should stream without error.
3. Restart the agent; transient daemon disconnects resolve on restart.
4. Reduce --filter label constraints that may exclude everything and stress listener setup.
5. Update to the latest dozzle version if the error persists (possible bug).

if err := agentCmd.Run(args, embeddedCerts); err != nil {
  var wrapped error
  if errors.As(err, &wrapped) { log.Error().Err(wrapped).Msg("notification manager startup") }
  log.Fatal().Err(err).Msg("agent startup failed")
}

When it happens

Trigger: Internal listener startup failure, e.g. the Docker client service cannot establish the event/stat streams it subscribes to, or the manager is started twice / in an invalid state.

Common situations: Docker daemon becomes unresponsive between client creation and manager start; a regression or bad state after hot-reloading during development (air); misconfigured filters causing subscription setup to fail.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• failed to create docker client
• (await res.json().catch(() =>
• (await res.json().catch(() =>
• Failed to save destination
• dispatchers fetch failed

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

Appendix: source

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

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

	// Start first so matcher is available for LoadConfig
	if err := notificationManager.Start(); err != nil {
		return fmt.Errorf("failed to start notification manager: %w", err)
	}

	// Load existing notification config if available
	if file, err := os.Open(notificationConfigPath); err == nil {
		if err := notificationManager.LoadConfig(file); err != nil {
			log.Warn().Err(err).Msg("Failed to load notification config, starting fresh")
		} else {
			log.Info().Str("path", notificationConfigPath).Msg("Loaded notification config from disk")
		}
		file.Close()
	}

	// Create handler that wraps manager and persists config to disk
	notificationHandler := &persistingNotificationHandler{
		manager:    notificationManager,
		configPath: notificationConfigPath,
	}

View on GitHub (pinned to d9463cbe21)