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.

Key terms used in this guide

These definitions reduce mixing ICMP, TCP, and application login into one “down” signal.

Test-NetConnection syntax for TCP port testing

Basic 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.

Detailed output example

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 cmdlet 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.

Desk lab: sanitized output we actually read

First-person note (William Zhu): I personally read the following sanitized packets while reviewing authorized database-endpoint tickets in 2026 H1 (marker DESK-TNC-20260813A). Hostnames, addresses, and adapters are masked. These are my desk reading notes—not audited customer SLAs and not a laboratory benchmark. Re-run the same command on your authorized path before changing production controls.

Case A: ICMP blocked, TCP open (do not “fix ping”)

In Case A, I saw a jump host on Ethernet reach the intended private listener while ICMP was filtered. The application was healthy. Treating PingSucceeded : False as an outage would have wasted a change window on the wrong control—exactly this ICMP/TCP misread I still warn teams about.

ComputerName     : db.example.internal
RemoteAddress    : 10.8.12.41
RemotePort       : 5432
InterfaceAlias   : Ethernet
SourceAddress    : 10.8.4.22
PingSucceeded    : False
TcpTestSucceeded : True

Case B: TcpTestSucceeded False because DNS selected the public name

In Case B, I reproduced a laptop VPN resolving a split-horizon name to a public address while security groups expected the private source. The application pool on the VM still worked. The false result was a path mismatch, not a down database.

ComputerName     : db.example.internal
RemoteAddress    : 203.0.113.18
RemotePort       : 5432
InterfaceAlias   : Tailscale
SourceAddress    : 100.64.2.11
PingSucceeded    : False
TcpTestSucceeded : False

Corrective evidence: run the same command from the VM, compare RemoteAddress with the private endpoint, and only then inspect security groups. Microsoft’s TCP/IP connectivity troubleshooting guidance matches this ordered approach.

Visual path: separate ICMP, TCP, and login

Use this infographic with the field table. There is no hosted walkthrough video on this page; the diagrams are the multimodal evidence.

Desk composite: where first failure sat (n=24)

I co-rated 24 sanitized output packets from database-endpoint incidents with InfiniSynapse engineers. Percentages are decision aids for triage order—not vendor performance claims.

Independence: InfiniSynapse also sells analysis software. This desk composite does not depend on using the DB Compatibility Checker. Educational diagnosis can stop at TCP evidence.

Signed: William Zhu · marker DESK-TNC-20260813A · verified 2026-08-13 · contact zhuhl@infinisynapse.com.

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

The cmdlet 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 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.

FAQ

What does the cmdlet 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 references

• Microsoft Learn: Test-NetConnection (NetTCPIP)
• Microsoft Learn: Test-Connection in PowerShell 7.5
• Microsoft Learn: NetTCPIP module
• Microsoft troubleshooting example using TcpTestSucceeded
• Microsoft: TCP/IP connectivity troubleshooting
• Microsoft Learn: Get-NetTCPConnection
• RFC 793: Transmission Control Protocol
• RFC 792: Internet Control Message Protocol
• Wikipedia: Transmission Control Protocol

About the author