Port is not listening on z/OS

Port is not listening on z/OS almost always sits below the application - the program is fine, the packets never arrive. Start at the socket and work outward: listener, route, firewall, DNS.

What it means

• Connection refused means the TCP SYN reached the host but nothing listens on that port - the server side is down or the port is wrong.
• Connection timed out means the SYN got no answer at all - a firewall is dropping it or the route is broken.
• z/OS listens through the TCP/IP stack started task, and each application (TN3270, FTP, z/OSMF) binds its own port.

Common causes

• Application listener not started on z/OS, or started on the wrong LPAR or port.
• Firewall between the distributed network and z/OS dropping the port, often after a firewall rule change.
• DNS resolving the hostname to a stale or wrong IP, for example a decommissioned LPAR.
• Client forcing IPv6 while the z/OS stack or application only binds IPv4, or the reverse.
• Routing change sending traffic down an asymmetric path that a stateful firewall blocks.
• Stale half-open connections left behind after a z/OS or network device restart.

How to diagnose

• On z/OS run D TCPIP,TCPIP,NETSTAT,PORTLIST to prove which ports actually have listeners.
• From the client run telnet host port or PowerShell Test-NetConnection -ComputerName host -Port port - refused versus timeout tells you where it dies.
• Run nslookup on the hostname and compare the answer against the HOME statements in the TCP/IP profile.
• Run traceroute from both ends to spot the dead or asymmetric hop.
• Check the TCP/IP started task messages in SYSLOG for stack or interface errors around the failure time.

How to fix it

• Start or restart the application listener on z/OS and confirm the port appears in NETSTAT PORTLIST.
• Open the exact port and protocol in the firewall rule for the client subnet, confirmed with the network team using the failure timestamp.
• Correct the DNS entry or point the client at the right hostname, then flush stale resolver caches.
• Align IPv4 and IPv6 on both ends so client and server speak the same family.
• After any restart, recycle hung client connections and re-run a connectivity smoke test before release.

Example: Check listeners and connections on z/OS

PORTLIST proves the listener exists; a refused connection with a listed port points at the firewall, a timeout points at routing.

Interview tip

• Q: A distributed app gets connection refused to z/OS but ping works. Port is not listening on z/OS - where do you look first?
• A: Ping only proves ICMP reaches the LPAR, so I check whether anything listens on the port with NETSTAT PORTLIST on z/OS. If the port is listed, the refusal happens downstream and I check the firewall rule for that subnet. If the port is not listed, the application listener is down or bound to the wrong stack.

Prevention checklist

• Monitor every production listener port from outside z/OS and alert when it stops answering.
• Record firewall rules per application port in the runbook so changes get reviewed before rollout.
• Use DNS names in client configs, never hard-coded IPs, and keep forward and reverse zones in sync.
• Run a connectivity smoke test after any network or z/OS restart before releasing the system.