{"record":{"id":"bfb4cc5598fd297f","repo":"AdguardTeam/AdGuardHome","slug":"starting-dhcp-server-w","errorCode":null,"errorMessage":"starting dhcp server: %w","messagePattern":"starting dhcp server: %w","errorType":"http","errorClass":null,"httpStatus":400,"severity":"error","filePath":"internal/dhcpd/http_unix.go","lineNumber":220,"sourceCode":"\t\t} else {\n\t\t\terr = fmt.Errorf(\"checking static ip: %w\", err)\n\n\t\t\treturn http.StatusInternalServerError, err\n\t\t}\n\t}\n\n\tif !hasStaticIP {\n\t\terr = aghnet.IfaceSetStaticIP(ctx, s.conf.Logger, cmdCons, ifaceName)\n\t\tif err != nil {\n\t\t\terr = fmt.Errorf(\"setting static ip: %w\", err)\n\n\t\t\treturn http.StatusInternalServerError, err\n\t\t}\n\t}\n\n\terr = s.Start(ctx)\n\tif err != nil {\n\t\treturn http.StatusBadRequest, fmt.Errorf(\"starting dhcp server: %w\", err)\n\t}\n\n\treturn 0, nil\n}\n\ntype dhcpServerConfigJSON struct {\n\tV4            *v4ServerConfJSON `json:\"v4\"`\n\tV6            *v6ServerConfJSON `json:\"v6\"`\n\tInterfaceName string            `json:\"interface_name\"`\n\tEnabled       aghalg.NullBool   `json:\"enabled\"`\n}\n\nfunc (s *server) handleDHCPSetConfigV4(\n\tconf *dhcpServerConfigJSON,\n) (srv DHCPServer, enabled bool, err error) {\n\tif conf.V4 == nil {\n\t\treturn nil, false, nil\n\t}","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/dhcpd/http_unix.go#L202-L238","documentation":"Raised when the DHCP server (v4 and/or v6) fails to start after a new configuration is applied via POST /control/dhcp/set_config. The wrapped error comes from the underlying DHCP server's Start method and typically indicates a socket-binding or interface problem (e.g. UDP port 67/68 or DHCPv6 ports already in use, missing CAP_NET_RAW/CAP_NET_ADMIN privileges, or a nonexistent interface).","triggerScenarios":"Calling the set_config HTTP endpoint with Enabled=true where s.Start(ctx) fails: another DHCP daemon (dnsmasq, systemd-networkd, an earlier AdGuard instance) holds UDP 67/68, the binary lacks raw-socket capabilities, or the configured interface name does not exist on the host.","commonSituations":"Running AdGuard Home alongside an existing DHCP server; running in a container without NET_ADMIN/NET_RAW capabilities; renaming or removing network interfaces after a config was saved; stale socket from a previous crashed instance.","solutions":["Check what holds the DHCP ports: ss -lunp | grep -E ':67|:68' (or :547 for DHCPv6) and stop the conflicting daemon (e.g. systemctl stop dnsmasq)","Ensure the binary has privileges: run as root/CAP_NET_ADMIN+CAP_NET_RAW, or set capabilities with setcap 'cap_net_raw,cap_net_admin=eip'","Verify the configured interface name exists (ip link) and fix InterfaceName in the config","If a previous AdGuard instance died uncleanly, make sure no orphaned process still holds the socket before retrying"],"exampleFix":"// before\nsudo dnsmasq --no-daemon   # still running elsewhere\ncurl -X POST http://127.0.0.1:3000/control/dhcp/set_config -d '{\"enabled\":true,...}'\n// -> 400 starting dhcp server: listen udp :67: bind: address already in use\n\n// after\nsudo systemctl stop dnsmasq\ncurl -X POST http://127.0.0.1:3000/control/dhcp/set_config -d '{\"enabled\":true,...}'\n// -> 200","handlingStrategy":"validation","validationCode":"// before enabling, check ports and interface\nfunc dhcpPrereqsOK(iface string) bool {\n\tif _, err := net.InterfaceByName(iface); err != nil { return false }\n\tfor _, p := range []int{67, 68} {\n\t\tc, err := net.ListenPacket(\"udp\", fmt.Sprintf(\":%d\", p))\n\t\tif err != nil { return false }\n\t\tc.Close()\n\t}\n\treturn true\n}","typeGuard":null,"tryCatchPattern":"err := srv.Start(ctx)\nif err != nil {\n    if strings.Contains(err.Error(), \"address already in use\") { /* stop conflicting daemon, retry */ }\n    if strings.Contains(err.Error(), \"permission denied\") { /* re-run with CAP_NET_RAW */ }\n}","preventionTips":["Stop dnsmasq/isc-dhcp or any other DHCP daemon before enabling AdGuard's","Run the binary with CAP_NET_RAW/CAP_NET_ADMIN or as root","Verify interface names exist before saving the config"],"tags":["dhcp","network","socket-bind","adguard-home","configuration"],"backgroundTag":"port-already-in-use","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}