OTel collector "Failed to start: address already in use": port conflict fix
Fixes an OpenTelemetry collector that refuses to start because another process already holds its receiver port (usually 4317 or 4318). Use when the collector log names a specific address and port as already in use. Not for collector config syntax errors, exporter auth failures, or pipeline misconfiguration.
TL;DR
Another process is already bound to the port the collector wants - often a second collector instance, a leftover one from a bad shutdown, or another service on the same port. Find which process holds the port, then either stop the duplicate or change one side's port. If you genuinely need both running, give one of them a different port in its config.
OTel collector "Failed to start: address already in use": port conflict fixSteps
- Read the collector startup log and note the exact address and port it failed to bind.
Expected: You know the conflicting port, e.g. 4317 or 4318.
- Find the process holding that port with a socket listing command (for example ss with the listen and process flags, or lsof for the port).
Expected: You have a PID and process name for the holder.
- Decide which one should own the port. If it is a duplicate or stale collector, stop it. If it is a different service you need, change the port in one side's config.
Expected: The port is free, or you have a planned new port for one side.
- Start the collector again and confirm the receiver logs show it listening.
Expected: The collector starts cleanly and the receiver accepts connections.
Use this when
- The collector log says failed to start with address already in use on a receiver port.
- Two collector instances or a collector plus another OTLP receiver on one host.
- A collector that fails to start right after a previous one was killed.
Not for this skill when
- Collector config YAML syntax or schema errors (different fix).
- Exporter failures like auth errors or unreachable backends.
- Pipelines that start fine but drop or misroute telemetry.
Variant phrasings
otelcol bind: address already in use
opentelemetry collector port 4317 already in use
collector fails to start receiver port in use
Why it happens
Each receiver opens a TCP or UDP listener, and an operating system only allows one process per port. A second collector, a zombie process from an unclean shutdown, or an unrelated service on the same port all produce the same bind failure.
Edge cases
- A socket in TIME_WAIT is not a real conflict - if nothing owns the port, just retry.
- Docker port mappings can collide with host processes and with each other; check both.
- Two pipelines in one config accidentally using the same receiver port fail the same way.
- On systemd hosts, a failed collector may restart-loop and hold nothing while another copy holds the port - check for duplicates first.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_jNbYlm1DRddgvjidmf60iQ