From 853f7442f2e2e1638bf444975df3fbf3b1f89ec6 Mon Sep 17 00:00:00 2001 From: Brian Hartford Date: Fri, 5 Dec 2025 09:43:05 -0500 Subject: [PATCH 1/2] Create port_conflict --- .../en/agent/troubleshooting/port_conflict | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 content/en/agent/troubleshooting/port_conflict diff --git a/content/en/agent/troubleshooting/port_conflict b/content/en/agent/troubleshooting/port_conflict new file mode 100644 index 00000000000..9f7589ee6f6 --- /dev/null +++ b/content/en/agent/troubleshooting/port_conflict @@ -0,0 +1,99 @@ +title: Troubleshooting Windows Agent Startup Failures Due to Port Conflicts +description: Diagnose and resolve Windows Agent startup failures caused by another service binding to a required port. +further_reading: + • link: “/agent/troubleshooting/debug_mode/” +tag: “Documentation” +text: “Agent Debug Mode” + +When running the Datadog Agent on Windows, the Agent may fail to start if another process is already listening on one of the ports required by the Agent’s components. This issue commonly appears in the Windows Event Viewer or Agent logs as “address already in use” or “port already allocated”. + +This guide explains which ports the Agent requires, how to check whether another service is using one of those ports, and how to resolve the conflict. + +## Agent ports on Windows + +The Datadog Agent uses several local ports depending on which features are enabled. + +Component: DogStatsD +Default port: 8125 UDP +Purpose: Metrics, distributions, and custom metrics + +Component: Trace Agent (APM) +Default port: 8126 TCP +Purpose: Receiving application traces + +Component: Live Processes +Default port: 6162 TCP +Purpose: Process data collection + + +If another application binds to any of these ports, the Agent will fail to start or one of its subsystems will refuse to run. + +Common symptoms + +You may see: + • The Agent GUI reporting that the Datadog Agent service failed to start + • Event Viewer logs showing “Only one usage of each socket address is normally permitted” + • Trace or DogStatsD logs containing “bind: Address already in use” + • datadog-agent.exe status showing components not running + +Checking for port conflicts on Windows + +You can use netstat or PowerShell to determine whether another process is listening on a required Agent port. + +Checking with netstat (Command Prompt): + +Use netstat to check whether another process is listening on a required Agent port: +``` +netstat -ano | findstr : +``` +Replace with the port you want to check, such as 8125, 8126, or 6162. + + +If output appears, the final number on the line is the PID of the process using the port. + +Checking with PowerShell: +``` +Get-NetTCPConnection -LocalPort 8126 +Get-NetUDPEndpoint -LocalPort 8125 +``` +To identify which process is using the port: +``` +Get-Process -Id +``` +Resolving the port conflict + +Option 1: Stop or reconfigure the conflicting service +If a non-Datadog service is using one of the Agent ports, stop the service or change its port configuration. + +Option 2: Change the Datadog Agent port configuration +You can change DogStatsD or APM ports in the Agent config file located at: +``` +C:\ProgramData\Datadog\datadog.yaml +``` +Example to change DogStatsD port: +``` +dogstatsd_port: 9125 +``` +Example to change the APM receiver port: +``` +apm_config: +receiver_port: 9126 +``` + +Restart the Agent service after modifying configuration. + +Option 3: Firewall or endpoint security interference +Some security tools may reserve or block ports. Ensure these tools allow the Datadog Agent to bind locally to its ports. + +Verifying that the issue is resolved + +Restart the Agent service: +net stop datadogagent +net start datadogagent + +Then verify components with: +``` +"%ProgramFiles%\Datadog\Datadog Agent\bin\agent.exe" diagnose +``` + +All required subsystems should show as “Running”. From d60175eaa346fe772bc6935c49d92eb1803a4761 Mon Sep 17 00:00:00 2001 From: Brian Hartford Date: Fri, 5 Dec 2025 10:22:28 -0500 Subject: [PATCH 2/2] Update and rename port_conflict to port_conflict.md --- .../troubleshooting/{port_conflict => port_conflict.md} | 8 -------- 1 file changed, 8 deletions(-) rename content/en/agent/troubleshooting/{port_conflict => port_conflict.md} (91%) diff --git a/content/en/agent/troubleshooting/port_conflict b/content/en/agent/troubleshooting/port_conflict.md similarity index 91% rename from content/en/agent/troubleshooting/port_conflict rename to content/en/agent/troubleshooting/port_conflict.md index 9f7589ee6f6..7e43dafdf69 100644 --- a/content/en/agent/troubleshooting/port_conflict +++ b/content/en/agent/troubleshooting/port_conflict.md @@ -82,14 +82,6 @@ receiver_port: 9126 Restart the Agent service after modifying configuration. -Option 3: Firewall or endpoint security interference -Some security tools may reserve or block ports. Ensure these tools allow the Datadog Agent to bind locally to its ports. - -Verifying that the issue is resolved - -Restart the Agent service: -net stop datadogagent -net start datadogagent Then verify components with: ```