Skip to main content
SysAdmin Shell Scripting Essentials

PowerShell tnc (Test-NetConnection) Syntax, Flags, and

3 min read

Test-NetConnection (tnc) is a PowerShell cmdlet for network diagnostics: ping, TCP port tests, traceroute, and detailed connectivity reports. Part of the NetTCPIP module, requires Windows 8/Server 2012 R2 or later.

tnc 192.168.1.1 -port 443 | Select-Object TcpTestSucceeded

Syntax

Test-NetConnection [[-ComputerName] <string>] [-CommonTCPPort <string>] [-Port <int>] [-TraceRoute] [-Hops <int>] [-InformationLevel <string>] [-Detailed] [-ConstrainInterface <int>] [-ConstrainScope <string>] [<CommonParameters>]

Alias: tnc. Requires Windows 8/Server 2012 R2 or later; available in PowerShell 7+ on Linux/macOS but with limited flags.

Options and Flags

Flag Type Default Description
-ComputerName String None Target host (IP or FQDN).
-Port Int None TCP port to test (1–65535).
-CommonTCPPort String None Well-known port name: HTTP, HTTPS, RDP, SMB, etc.
-TraceRoute Switch False Perform a traceroute to the target.
-Hops Int 30 Max hops for traceroute (default 30).
-InformationLevel String “Detailed” Output verbosity: “Detailed” or “Quiet”.
-Detailed Switch False Alias for -InformationLevel Detailed.
-ConstrainInterface Int None Force test over a specific network interface index.
-ConstrainScope String None Force test over a specific routing scope (e.g., link-local).
See also  Gogs Install: Deploy Self-Hosted Git Server on Linux | CLI

Usage Examples

Example 1: Basic ping connectivity

tnc 192.168.1.1

Performs ICMP echo test to 192.168.1.1. Returns PingSucceeded and round-trip time. ICMP does not require admin rights, but firewalls may block it.

Example 2: Test TCP port with detailed output

tnc secureideas.com -Port 443 -Detailed

Checks if TCP port 443 is open. -Detailed shows full output: TcpTestSucceeded, RTT, remote address, and interface details. Equivalent to nc -zv secureideas.com 443.

Example 3: Run traceroute with hop limit

tnc 8.8.8.8 -TraceRoute -Hops 15

Traces path to 8.8.8.8 with up to 15 hops. Outputs list of intermediate router IPs. Combine with -Port to test both TCP and route simultaneously.

Troubleshooting and Common Errors

Error / Symptom Root Cause Resolution
Cmdlet not recognized Windows version older than 8/2012 R2, or NetTCPIP module missing. Use Get-Module -ListAvailable NetTCPIP to verify; upgrade OS or use System.Net.Sockets.TcpClient as fallback.
PingSucceeded = False (TCP works) ICMP blocked by firewall. Run PowerShell as Administrator, or rely on TcpTestSucceeded.
TcpTestSucceeded = False on known open port Firewall outbound rule blocking TCP; service not listening; intermediate hop dropping. Use tnc target -Port 443 -TraceRoute to isolate failure hop.
Timeout or slow response Network latency, packet loss, or rate-limiting. Timeout not configurable in tnc; use native tools like nc -w via WSL for explicit timeout control.

Output Fields

Test-NetConnection is a cmdlet, not an executable; it does not return numeric exit codes. Evaluate these key output fields for operational decisions:

Field Type Meaning
PingSucceeded Boolean True if ICMP echo reply received.
TcpTestSucceeded Boolean True if TCP SYN-ACK received on specified port.
RemotePort Int Port tested (present only if -Port used).
RoundTripTime Int (ms) Measured RTT for successful probe.
TraceRoute Array List of hop IPs when -TraceRoute is enabled.
See also  Linux mv Command Reference – Syntax, Exit Codes, Troubleshooting

Cross-Platform Notes (PowerShell Core)

In PowerShell 7+ on Linux and macOS, Test-NetConnection is available but lacks -TraceRoute and -CommonTCPPort flags due to missing Windows-specific APIs. Use -ComputerName and -Port for basic TCP connectivity; fall back to native tools (traceroute, mtr, nc) for traceroute or port scanning. Example cross-platform:

pwsh -Command "Test-NetConnection -ComputerName 8.8.8.8 -Port 53 -InformationLevel Quiet"

Frequently Asked Questions

What is the difference between -CommonTCPPort and -Port?

Answer: -CommonTCPPort accepts predefined service names (HTTP, RDP, SMB) and maps to standard ports automatically. -Port requires a numeric port (1–65535) and is used for non-standard or custom ports. Both perform a TCP connection test and require -ComputerName.

When should I use -TraceRoute?

Answer: Use -TraceRoute to diagnose network path latency and hop failures. It runs a traceroute after the TCP test. Combine with -Hops to limit the maximum number of hops (default 30). Not available on PowerShell Core for Linux/macOS.

How to fix ‘cmdlet not recognized’ error?

Answer: This occurs on Windows versions older than 8/Server 2012 R2 or if the NetTCPIP module is missing. Verify with Get-Module -ListAvailable NetTCPIP. Upgrade the OS or use System.Net.Sockets.TcpClient as an alternative.

Why does PingSucceeded show False even though TCP works?

Answer: ICMP is often blocked by firewalls. Run PowerShell as Administrator to allow raw ICMP, or rely on TcpTestSucceeded for connectivity checks.

Does tnc work on Linux or macOS?

Answer: Yes, in PowerShell 7+ for basic TCP tests with -ComputerName and -Port. However, -TraceRoute and -CommonTCPPort are unavailable. Use native tools for advanced diagnostics.

See also  Remove Winsxs: Syntax, Examples, Flags & Production Guide

How to test multiple ports quickly?

Answer: Use a loop over an array of ports. For parallel execution in PowerShell 7+, use ForEach-Object -Parallel with -ThrottleLimit. Example:

$ports = 80,443,3389,8080
$ports | ForEach-Object -Parallel {
    Test-NetConnection -ComputerName server01 -Port $_ -InformationLevel Quiet
} -ThrottleLimit 10