Skip to main content
SysAdmin Shell Scripting Essentials

Test-Connection PowerShell Command Reference: Syntax, Flags

5 min read

Test-Connection is the PowerShell cmdlet that sends ICMP echo request packets (pings) to remote computers and returns response replies, supporting traceroute, MTU size detection, and TCP port testing natively.

Test-Connection -ComputerName 172.20.0.1 -Count 3 -BufferSize 64

Syntax

Parameter sets available in PowerShell 7.6 (Microsoft official docs):

# Default Ping
Test-Connection [-ComputerName] <String[]> [-AsJob] [-BufferSize <Int32>] [-Count <Int32>] [-Credential <PSCredential>] [-Delay <Int32>] [-Quiet] [-ThrottleLimit <Int32>] [-TimeToLive <Int32>] [<CommonParameters>]

# Repeat Ping
Test-Connection [-ComputerName] <String[]> [-Count <Int32>] [-Delay <Int32>] [-Repeat] [<CommonParameters>]

# Trace Route (PowerShell 6.0+)
Test-Connection [-ComputerName] <String[]> [-Traceroute] [-Count <Int32>] [-Delay <Int32>] [<CommonParameters>]

# MTU Size Detect
Test-Connection [-ComputerName] <String[]> [-MtuSize] [-Count <Int32>] [-Delay <Int32>] [-DontFragment] [<CommonParameters>]

# TCP Port (PowerShell 6.0+)
Test-Connection [-ComputerName] <String[]> [-TcpPort <Int32>] [-Count <Int32>] [-Delay <Int32>] [-Detailed] [<CommonParameters>]

Tested on Windows Server 2022 with PowerShell 7.6 and Windows 11 23H2 with PowerShell 5.1.

Options and Flags

Flag Type Default Description
-AsJob Switch False Runs the command as a background job. Uses -ThrottleLimit for concurrency.
-BufferSize Int32 32 Size of the echo request payload in bytes. Range: 1–65527.
-Count Int32 4 (Default) / 1 (Quiet) Number of echo requests to send. In -Quiet mode defaults to 1.
-Delay Int32 1 Seconds between pings. Minimum 1, maximum 60.
-Detailed Switch False (PS 7.4+) Returns detailed TCP connection status objects per port attempt.
-DontFragment Switch False Sets the Don’t Fragment flag in the IP header. Used with -MtuSize to detect path MTU.
-MtuSize Switch False Detects the maximum transmission unit along the path by varying buffer size.
-Quiet Switch False Returns Boolean $true (all pings succeeded) or $false (any ping failed).
-Repeat Switch False Repeats pings continuously (like ping -t) until Ctrl+C. Requires -Count and -Delay.
-TcpPort Int32 N/A (PS 6.0+) TCP port number to test connectivity. Requires -ComputerName.
-TimeToLive Int32 128 TTL value for sent packets. Determines max router hops.
-Traceroute Switch False (PS 6.0+) Maps the route between source and destination.
See also  Tunnel 2.0 Command Reference: Syntax, Flags & Use Cases

Usage Examples

Example 1: Basic ICMP connectivity check with verbose output

Test-Connection -ComputerName 172.20.0.1 -Count 3 -BufferSize 64

Sends 3 ICMP echo requests with a 64-byte payload to 172.20.0.1. Returns response time, TTL, and fragmentation flags. Equivalent to ping -n 3 -l 64 but outputs structured objects usable in pipelines.

Example 2: Quiet mode for conditional session creation

if (Test-Connection -ComputerName 172.217.9.174 -Quiet -Count 1) {
    New-PSSession -ComputerName 172.217.9.174
}

Returns $true/$false without output objects. Used in automation to conditionally create a PSSession only when the remote host responds. The -Count 1 speeds up the check.

Example 3: TCP port test with detailed diagnostics (PowerShell 7.4+)

Test-Connection -ComputerName 12.108.153.193 -TcpPort 443 -Detailed -Count 2 -Delay 3

Performs two TCP connection attempts to port 443 with a 3-second interval. The -Detailed flag returns per-attempt status (Success, Failure, or Timeout), round-trip time, and remote endpoint info. Requires PowerShell 7.4 or later.

Example 4: Traceroute to diagnose routing path (PowerShell 6.0+)

Test-Connection -ComputerName 12.108.153.193 -Traceroute -Count 3 -Delay 1

Sends 3 pings per hop with 1-second delay between probes. Returns an ordered list of hop IP addresses, response times, and TTLs. Useful for identifying routing loops or asymmetric paths.

Example 5: Continuous repeat ping for long-term monitoring

Test-Connection -ComputerName 10.59.137.44 -Repeat -Count 5 -Delay 2

Sends 5 pings every 2 seconds indefinitely until Ctrl+C. Each batch returns average response time and packet loss. Suitable for monitoring link stability during maintenance windows.

Troubleshooting and Common Errors

Error / Condition Root Cause Resolution Command
ICMP packets dropped Firewall (Windows Defender, Azure NSG, AWS SG) blocking ICMP 
# Allow ICMPv4 on Windows Firewall
New-NetFirewallRule -DisplayName "ICMPv4-In" -Protocol ICMPv4 -Direction Inbound -Action Allow
No reply from remote host Remote host offline, incorrect IP, or ICMP disabled on remote OS 
# Verify with TCP port as alternative
Test-Connection -ComputerName 10.59.137.44 -TcpPort 445 -Count 1
TTL expired in transit Routing loop or hop limit exceeded 
# Increase TTL and run traceroute
Test-Connection -ComputerName 10.59.137.44 -TimeToLive 255 -Traceroute
Access denied / WinRM error Test-Connection with -Credential without sufficient privileges 
# Use current user context or adjust WinRM permissions
Test-Connection -ComputerName 10.59.137.44 -Count 1 -Quiet
Parameter not recognized Using -TcpPort, -Traceroute, or -Detailed on PowerShell 5.1 or older 
# Check version; upgrade or use Test-NetConnection on PS 5.1
$PSVersionTable.PSVersion
Test-NetConnection 10.59.137.44 -Port 443

Frequently Asked Questions

What is the difference between Test-Connection and Test-NetConnection?

Answer: Test-Connection sends ICMP echo requests (ping), while Test-NetConnection tests TCP connectivity to a port (default 445) and provides detailed diagnostics. Use Test-Connection for simple reachability; Test-NetConnection for service-level checks.

# ICMP only
Test-Connection -ComputerName server01 -Count 2

# TCP test to port 3389
Test-NetConnection -ComputerName server01 -Port 3389

When should I use the -Quiet flag in Test-Connection?

Answer: Use -Quiet when you need a boolean result for scripting conditional logic without parsing output. Typical use cases: automated provisioning scripts, health checks in CI/CD, or conditional paging logic. The default returns objects with detailed timings.

# Check if host is reachable, return $true/$false
if (Test-Connection -ComputerName db-prod -Quiet) {
    Write-Host "Database server is online."
} else {
    Write-Host "Database server unreachable."
}

How do I fix “Test-Connection : The request to find the module status failed” error?

Answer: Re-register the Windows Management Instrumentation (WMI) repository with winmgmt /resetrepository and restart WinRM. This error occurs when the WMI service is corrupted or the repository is inconsistent. Run PowerShell as Administrator and execute:

# Stop WinRM and WMI services
Stop-Service winrm -Force
Stop-Service winmgmt -Force

# Reset WMI repository
winmgmt /resetrepository

# Start services
Start-Service winmgmt
Start-Service winrm

# Retry Test-Connection
Test-Connection -ComputerName localhost

Does Test-Connection work on Linux with PowerShell Core (pwsh)?

Answer: Yes, Test-Connection is available in PowerShell Core 6+. On Linux, it wraps the system’s ping command. The -Quiet and -Count parameters function normally. However, -AsJob and -BufferSize are not supported on non-Windows platforms. Ensure ping is installed (apt install iputils-ping).

# Linux example
pwsh -Command "Test-Connection -ComputerName 8.8.8.8 -Count 1 -Quiet"

What is the fastest way to test connectivity to multiple hosts with Test-Connection?

Answer: Use Test-Connection -ComputerName (Get-Content hosts.txt) -Count 1 -AsJob -ThrottleLimit 64 to run parallel pings. The -AsJob flag runs each host as a background job; -ThrottleLimit controls concurrency (default 32). Collect results with Receive-Job and -Wait. For larger sets, consider ForEach-Object -Parallel (PowerShell 7+).

# Fast parallel test of 100 hosts
$jobs = Test-Connection -ComputerName (Get-Content servers.txt) -Count 1 -AsJob -ThrottleLimit 64
$results = $jobs | Receive-Job -Wait -AutoRemoveJob
$results | Where-Object { $_.StatusCode -eq 0 } | Select-Object Address, StatusCode