{"record":{"id":"73fd4f3f05f278f3","repo":"amir20/dozzle","slug":"failed-to-listen-w","errorCode":null,"errorMessage":"failed to listen: %w","messagePattern":"failed to listen: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/support/cli/agent_command.go","lineNumber":156,"sourceCode":"\t}\n}\n\nfunc (a *AgentCmd) Run(args Args, embeddedCerts embed.FS) error {\n\tif args.Mode != \"server\" {\n\t\treturn fmt.Errorf(\"agent command is only available in server mode\")\n\t}\n\tclient, err := docker.NewLocalClient(args.Hostname)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create docker client: %w\", err)\n\t}\n\tcerts, err := ReadCertificates(embeddedCerts, args.CertPath, args.KeyPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to read certificates: %w\", err)\n\t}\n\n\tlistener, err := net.Listen(\"tcp\", args.Agent.Addr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to listen: %w\", err)\n\t}\n\tconst agentAddrFile = \"/tmp/dozzle-agent.addr\"\n\tif err := os.WriteFile(agentAddrFile, []byte(args.Agent.Addr), 0644); err != nil {\n\t\treturn fmt.Errorf(\"failed to write agent address file: %w\", err)\n\t}\n\tgo StartEvent(args, \"\", client, \"agent\")\n\n\tctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)\n\tdefer stop()\n\n\t// Create shared client service (single ContainerStore for both agent server and notifications)\n\tclientService := docker_support.NewDockerClientService(client, args.Filter)\n\n\t// Create notification manager using the shared client service\n\tconst notificationConfigPath = \"./data/notifications.yml\"\n\tclients := []container_support.ClientService{clientService}\n\tnotificationManager := notification.NewManager(\n\t\tnotification.NewContainerLogListener(ctx, clients),","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/amir20/dozzle/blob/d9463cbe21874e44ab79db6fa63e746ca7d22928/internal/support/cli/agent_command.go#L138-L174","documentation":"Returned by AgentCmd.Run when net.Listen(\"tcp\", args.Agent.Addr) fails to bind the gRPC listener. The address comes from --agent-addr (default :7007, env DOZZLE_AGENT_ADDR). Typical causes are the port already being used or binding to an address that does not exist on the host.","triggerScenarios":"Another dozzle agent (or any process) already listens on 7007; binding to a specific IP not assigned to the host; privileged port below 1024 without privileges; invalid host:port syntax.","commonSituations":"Two agents accidentally started on one host; old agent process still running after crash (check /tmp/dozzle-agent.addr); container network conflicts; changing DOZZLE_AGENT_ADDR to a typo'd host.","solutions":["Check what holds the port: `lsof -i :7007` or `ss -ltnp | grep 7007`, then stop it.","Change the port: --agent-addr :7008 or DOZZLE_AGENT_ADDR=:7008 (update the main server's agent endpoint too).","If binding to a specific IP, confirm it exists on the host (`ip addr`).","Kill leftover agent processes: `pkill dozzle`.","Use a port above 1024 if running as non-root."],"exampleFix":"// before\nDOZZLE_AGENT_ADDR=127.0.0.1:7007 ./dozzle agent  # bind fails, IP not local\n// after\nDOZZLE_AGENT_ADDR=:7007 ./dozzle agent","handlingStrategy":"validation","validationCode":"if ss -ltn | grep -q ':7007 '; then echo 'port 7007 already in use'; exit 1; fi","typeGuard":null,"tryCatchPattern":"if err := agentCmd.Run(args, embeddedCerts); err != nil {\n  if strings.Contains(err.Error(), \"failed to listen\") {\n    log.Fatal().Err(err).Msg(\"port busy or invalid bind address; adjust --agent-addr\")\n  }\n}","preventionTips":["Reserve one agent port per host","Check listeners with `ss -ltn` before start","Clean up stale agent processes and /tmp/dozzle-agent.addr","Use ports above 1024 for non-root runs"],"tags":["network","bind","grpc"],"backgroundTag":"address-already-in-use","analyzedSha":"d9463cbe21874e44ab79db6fa63e746ca7d22928","analyzedAt":"2026-09-07T10:08:55.855Z","contentChangedAt":"2026-09-07T10:08:55.855Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}