How to Test a TCP Port Connection (PortQry) in Batch Script

A critical part of network troubleshooting is verifying connectivity to a specific service on a server. It's not enough to know if you can ping the server; you need to know if the specific port for your application (like a web server on port 443 or a database on port 1433) is open and listening. While telnet was the classic tool for this, the modern and far more powerful utility is PortQry.

This guide will introduce you to the PortQry tool, explain how to use it to test TCP port connectivity from a batch script, and teach you how to interpret its %ERRORLEVEL% to programmatically determine if a port is open, closed, or filtered.

What is PortQry? (and where to get it)

PortQry is a free, advanced command-line port scanner from Microsoft. It is superior to telnet for scripting because:

• It has a silent mode for clean output.
• It provides a specific %ERRORLEVEL% to indicate the port's status.
• It can also test UDP ports, which telnet cannot.
• It does not get "stuck" waiting for input like telnet can.

Where to get it:

• PortQry is not included with Windows by default.
• You must download it from the official Microsoft Download Center. Search for "PortQryV2.exe".
• After downloading, extract portqry.exe and place it in your system's PATH (like C:\Windows\System32) or in the same directory as your batch script.

The Core Command Syntax

The basic syntax for a simple TCP port test is: portqry -n <server> -p tcp -e <port_number> [options]

• -n <server>: The name or IP address of the server to query.
• -p tcp: Specifies the protocol is TCP.
• -e <port_number>: Specifies the endpoint (the port number) to test.
• -q: Quiet mode. This is essential for scripting as it suppresses most of the output.

Basic Example: Checking a Web Server's HTTPS Port

This command will test if google.com is listening on TCP port 443 (the standard port for HTTPS).

@ECHO OFF
ECHO --- Testing TCP Port 443 on google.com ---
ECHO.
portqry -n google.com -p tcp -e 443

PortQry provides a clear, human-readable report as output:

Querying target system called:

 google.com

Attempting to resolve name to IP address...

Name resolved to 142.250.191.174

querying...

TCP port 443 (https service): LISTENING

Interpreting the Results (%ERRORLEVEL%) for Scripts

This is the most powerful feature of PortQry for automation. After it runs, it sets the %ERRORLEVEL% variable to one of three values:

%ERRORLEVEL%	Port Status	Meaning
0	LISTENING	Success. The port is open and a service is actively listening.
1	NOT LISTENING	Failure. The server responded, but no service is running on that port.
2	FILTERED	Failure. No response was received from the server. A firewall is likely blocking the port.

Example of Script to Check the Result:

@ECHO OFF
SET "SERVER=google.com"
SET "PORT=443"

ECHO Checking %SERVER% on port %PORT%...
portqry -n %SERVER% -p tcp -e %PORT% -q

IF %ERRORLEVEL% EQU 0 (
    ECHO [SUCCESS] The port is open and LISTENING.
) ELSE IF %ERRORLEVEL% EQU 1 (
    ECHO [FAILURE] The port is CLOSED (Not Listening).
) ELSE IF %ERRORLEVEL% EQU 2 (
    ECHO [FAILURE] The port is FILTERED (likely by a firewall).
)

note

Note the use of -q to run in quiet mode. This suppresses the detailed output but still sets the %ERRORLEVEL% correctly.

Common Pitfalls and How to Solve Them

Problem: 'portqry' is not recognized...

This means portqry.exe is not in your PATH or in the current directory.

Solution: Download PortQry from Microsoft and place portqry.exe in C:\Windows\System32 or in the same folder as your script.

Problem: Understanding "FILTERED" vs. "NOT LISTENING"

This is a key diagnostic distinction:

• NOT LISTENING (1): You successfully reached the server, but the application you're looking for isn't running or isn't configured for that port. This is an application-level problem.
• FILTERED (2): Your connection attempt was dropped and you got no response at all. This is almost always a network-level problem, meaning a firewall on the server, on your client, or somewhere in between is blocking the traffic.

Solution: Knowing the difference tells you where to look. If it's NOT LISTENING, check the service on the server. If it's FILTERED, check the firewall rules.

Problem: Testing UDP Ports

telnet cannot test UDP ports, but PortQry can.

Solution: Simply change the protocol in the command.

REM Test a DNS server on UDP port 53
portqry -n 8.8.8.8 -p udp -e 53

Practical Example: A Server Prerequisite Check Script

This script is designed to run before an application is installed. It checks that the new application server can communicate with the database server on the required SQL port (TCP 1433).

@ECHO OFF
SETLOCAL
SET "DB_SERVER=DB-PROD-01"
SET "SQL_PORT=1433"

ECHO --- Database Connectivity Prerequisite Check ---
ECHO This script will check if this server can connect to
ECHO the database server '%DB_SERVER%' on port %SQL_PORT%.
ECHO.

WHERE portqry > NUL 2> NUL
IF %ERRORLEVEL% NEQ 0 (
    ECHO [FATAL] PortQry.exe not found. Please download and install it.
    GOTO :End
)

ECHO Performing port check...
portqry -n %DB_SERVER% -p tcp -e %SQL_PORT% -q

IF %ERRORLEVEL% EQU 0 (
    ECHO [SUCCESS] Connection to the database port was successful.
    EXIT /B 0
) ELSE IF %ERRORLEVEL% EQU 1 (
    ECHO [FAILURE] Connection failed. The SQL Server is not listening on that port.
    EXIT /B 1
) ELSE (
    ECHO [FAILURE] Connection failed. The port is being blocked by a firewall.
    EXIT /B 1
)

:End
ENDLOCAL

Conclusion

PortQry is the essential tool for any script that needs to reliably test network port connectivity. Its ability to set a specific %ERRORLEVEL% based on the port's status makes it far superior to older tools like telnet.

Key takeaways:

• PortQry is not installed by default; you must download it from Microsoft.
• Use portqry -n <server> -p tcp -e <port> as the base command.
• Always use the -q (quiet) switch in scripts and check the %ERRORLEVEL%: 0 for LISTENING, 1 for NOT LISTENING, and 2 for FILTERED.
• It can also be used to test UDP ports.