Test-NetConnection Guide: Ports and Troubleshooting

What is Test-NetConnection?

The command is valuable because it preserves context that a bare success/failure check omits. A result can show which IP address DNS selected, which local interface and source address Windows chose, and whether ICMP and TCP outcomes differ. Those distinctions help prevent changes to the wrong firewall, DNS zone, or database server.

Test-NetConnection syntax for TCP port testing

Basic Test-NetConnection port example

Test-NetConnection -ComputerName db.example.internal -Port 5432

Replace the sanitized host and port with an endpoint you are authorized to test. Run the command from the same subnet, VM, jump host, or administrative context used by the application whenever possible. Testing from a laptop can follow different DNS, VPN, proxy, security-group, and egress paths.

Test-NetConnection with detailed output

Test-NetConnection -ComputerName db.example.internal -Port 1433 -InformationLevel Detailed

Detailed output is best for an incident record because it exposes the address and path Windows actually selected. Redact internal hostnames or addresses when sharing outside the authorized troubleshooting group, but retain enough context for another engineer to reproduce the test.

Test multiple database ports without treating them as a scanner

$ports = 1433, 3306, 5432, 1521
$ports | ForEach-Object {
  Test-NetConnection -ComputerName db.example.internal -Port $_ -InformationLevel Quiet
}

Use a small, explicit allowlist of expected ports and obtain authorization. A broad port range test changes the activity from targeted troubleshooting toward scanning, creates noisy evidence, and may violate policy. The built-in cmdlet tests one TCP port per invocation; automation should preserve the host, source, timestamp, port and purpose for each result.

How to read Test-NetConnection results

Can PingSucceeded be False while TcpTestSucceeded is True?

Yes. Ping uses ICMP, while -Port attempts TCP. Many networks block or deprioritize ICMP without blocking the application port. In that case, a ping warning does not invalidate a successful TCP result. Interpret each field according to its protocol and the question you are answering.

Fix TcpTestSucceeded False with evidence, not guesses

What does TcpTestSucceeded False mean?

It means the TCP connection attempt did not complete. It does not identify the cause by itself. The failure may occur before the target, at the target, or because the test selected an unexpected address or route. Record the complete output and the source context before changing configuration.

TcpTestSucceeded False troubleshooting sequence

1. Verify the targetConfirm environment, hostname, actual listener port, protocol, and whether the endpoint is private, public, proxy, pooler, writer, or reader.
2. Inspect name resolutionCompare RemoteAddress with the intended endpoint. Test from the application environment because split DNS and VPN state can change the answer.
3. Inspect source and routeCheck InterfaceAlias, SourceAddress, route table, VPN, subnet peering, private link, proxy, and return route.
4. Check policy boundariesReview egress rules, network ACLs, security groups, host firewall, endpoint allowlists, and network appliances for the exact source and destination port.
5. Check the listenerConfirm the service is running and bound to the intended interface and port. A database can be healthy locally while not listening on a remotely reachable address.

TcpTestSucceeded False but the application works

The test and application may use different hosts, ports, proxies, DNS answers, IP families, source networks, or timing. The application may reuse an existing pooled connection while a new connection is blocked. Capture the application's effective endpoint and run the test inside the same workload context before concluding that the command is wrong.

Use Test-NetConnection for database endpoints safely

Test-NetConnection is useful for PostgreSQL, MySQL, SQL Server, Oracle, MongoDB and other TCP endpoints because it does not need a username or password. Extract the authorized host and actual port from provider connection details or a sanitized connection URL. Do not assume a default when the environment uses a proxy, named instance, pooler, SSH tunnel, container mapping, or managed-service gateway.

Does TcpTestSucceeded True prove the database is ready?

No. It proves only that a TCP handshake completed to a listener on the selected address and port. It does not prove that the listener speaks the expected database protocol, that TLS verifies, that credentials are accepted, that the account can open the requested database, that a health query succeeds, or that the service has production capacity.

Test-NetConnection, Test-Connection, ping, and telnet differ

Can Test-NetConnection test UDP ports?

No. The -Port parameter performs a TCP connection test. UDP has no TCP-style handshake, and a missing response can mean the service is blocked, silent by design, expecting a specific payload, or absent. Use an authorized protocol-aware client or service-specific health check instead of relabeling a TCP result as UDP evidence.

How do I change the Test-NetConnection timeout?

The Windows PowerShell Test-NetConnection cmdlet does not expose the same -TimeoutSeconds parameter available to modern PowerShell Test-Connection. Search results often mix the two commands. Check Get-Command Test-NetConnection -Syntax, $PSVersionTable, and the documentation for the installed version before copying a timeout example.

Create a reproducible Test-NetConnection evidence record

• Context: UTC timestamp, Windows and PowerShell version, machine or workload, environment, VPN state, and administrator/non-administrator context.
• Sanitized target: database/service type, masked hostname when required, intended environment, port, private/public classification, and test authorization.
• Observed path: remote address, interface alias, source address, and route or next-hop evidence when relevant.
• Outcome: ping result, TCP result, duration, exact warning/error, and whether a subsequent TLS, login, or health-query test was attempted.
• Comparison: known-good source, first failure time, recent deployment/network changes, intermittent versus constant behavior, and remediation owner.

How to automate Test-NetConnection without losing context

Automation should emit structured records rather than screenshots or colored console text. For every authorized target, store the requested hostname, resolved address, port, source address, interface, Boolean TCP result, timestamp, duration, environment, and run identifier. Limit concurrency so the job does not resemble a port scan or overload a fragile endpoint. Define failure thresholds carefully: one failed attempt can reflect a transient route change, while repeated success does not prove database login or workload health. Protect internal topology in logs, set retention according to policy, and attach the result to a change or incident only after secrets and unnecessary identifiers are removed.

Test-NetConnection FAQ

What does Test-NetConnection do?

It is a Windows PowerShell NetTCPIP cmdlet that provides ping, TCP port, tracing, and route-selection diagnostics depending on its parameters.

How do I test a port with Test-NetConnection?

Run Test-NetConnection -ComputerName <host> -Port <port> -InformationLevel Detailed from the application's network path.

What does TcpTestSucceeded False mean?

The TCP attempt did not complete. Investigate target, DNS, source interface, route, policy boundaries, listener state, and timing.

Can Test-NetConnection test UDP ports?

No. -Port tests TCP. Use an approved protocol-aware UDP test for the actual service.

How do I set a Test-NetConnection timeout?

The Windows PowerShell cmdlet lacks the modern Test-Connection -TimeoutSeconds option. Verify the command and PowerShell version before using examples.

Does TcpTestSucceeded True prove a database is working?

No. It proves TCP reachability only, not database protocol, TLS, login, permissions, query success, capacity, or reliability.

Continue with a related guide

Use these closely related guides to verify the next layer of the workflow without mixing separate troubleshooting or decision intents.

• Database ports
• SQL Server port 1433
• MySQL port 3306

Official Test-NetConnection references

• Microsoft Learn: Test-NetConnection (NetTCPIP)
• Microsoft Learn: Test-Connection in PowerShell 7.5
• Microsoft Learn: NetTCPIP module
• Microsoft troubleshooting example using TcpTestSucceeded