nc (netcat): Usage, Options & Common CI Errors

nc opens raw TCP/UDP connections - the Swiss-army knife of networking.

netcat is the universal "is this port open yet?" tool in CI, used to wait for a database or service to accept connections. The catch: nc has several incompatible implementations.

What it does

nc establishes or listens on TCP/UDP connections and pipes stdin/stdout across them. In pipelines its most common job is a readiness probe: nc -z checks whether a port is accepting connections without sending data.

Common usage

Terminal

nc -z -v localhost 5432                         # is the port open?
nc -z -w 2 db.host 5432 && echo up              # with a 2s timeout
until nc -z localhost 8080; do sleep 1; done    # wait for a service
echo "PING" | nc -w1 host 6379                  # send and read once
nc -l 8080                                       # listen on a port

Options

Flag	What it does
-z	Zero-I/O: just scan, do not send data
-v	Verbose (prints succeeded/refused)
-w <secs>	Connect/idle timeout
-l	Listen mode (server)
-u	UDP instead of TCP
-p <port>	Source/local port (implementation-specific)

Common errors in CI

The flags differ by build: OpenBSD nc, GNU netcat, and Ncat (from nmap) are not identical. -z is missing on some builds, and BusyBox nc (Alpine) lacks -z entirely - use a connect-and-close like nc -w1 host port </dev/null, or install ncat. "nc: connect to host port (tcp) failed: Connection refused" means the service is not up yet (the basis of the until-loop wait pattern). "nc: invalid option -- z" tells you the wrong implementation is installed.