wait-port

library1.1.0jsnpmunverified

wait-port is a utility for Node.js environments designed to asynchronously wait for a network port, HTTP endpoint, or DNS record to become available. It is particularly useful in scripting scenarios, such as `docker-compose` setups, CI/CD pipelines, or application startup scripts, where service dependencies need to be met before proceeding. The package provides both a command-line interface (CLI) and a programmatic API. The current stable version is 1.1.0, released in September 2023, indicating an active development and maintenance cadence. Key features include configurable timeouts, support for TCP, HTTP (checking for 200-class status codes), and DNS resolution (`ENOTFOUND` handling), and robust IPv4/IPv6 support, including 'happy eyeballs' via `autoSelectFamily` introduced in v1.1.0. It distinguishes itself by its simplicity and dual usage model, making it a reliable choice for ensuring service readiness.

devops http-networking testing

npm install wait-port

github ↗package ↗

INSTALL

IMPORT

SIG · WAIT-PORT

wait-port

devopsjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

waitPort

✓ import waitPort from 'wait-port';

✗ import { waitPort } from 'wait-port';

The primary API function is a default export. Use default import for ESM.

waitPort (CommonJS)

✓ const waitPort = require('wait-port');

✗ const waitPort = require('wait-port').waitPort;

In CommonJS, the package's main function is directly exported.

CLI Usage

✓ wait-port localhost:8080 -t 5000

When installed globally, `wait-port` command is available. Locally, use `./node_modules/.bin/wait-port`.

Demonstrates programmatic use of `wait-port` to check for a port's availability with a timeout and handles both success and failure.

import waitPort from 'wait-port'; async function waitForMyService() { console.log('Attempting to connect to example.com:443...'); try { const params = { host: 'example.com', port: 443, timeout: 15000, // 15 seconds timeout output: 'dots' // Show progress dots }; const { open, ipVersion } = await waitPort(params); if (open) { console.log(`Successfully connected to example.com:443 on IPv${ipVersion}!`); // Proceed with application logic } else { console.log('Failed to connect to example.com:443 within the timeout period.'); process.exit(1); } } catch (error) { console.error(`An unexpected error occurred: ${error.message}`); process.exit(2); } } waitForMyService();

wait-port --version

Debug

Known issues

breakingThe return value of the programmatic API changed from a boolean to an object. Previously, it returned `true` or `false`. Now it returns `{ open: boolean, ipVersion?: 4|6 }`.

fix

Update your code to destructure the returned object, e.g., `const { open, ipVersion } = await waitPort(params);` and check `open` for status.

affects: >=1.0.0

gotchaVersion 0.2.13 incorrectly included a breaking change and should be avoided.

fix

Upgrade to version 0.2.14 for compatibility with Node 8, or 0.3.0/higher for Node 10+ compatibility.

affects: 0.2.13

gotchaWhen using the CLI or API, an `ENOTFOUND` error (address not found) will typically cause a failure. If you are waiting for DNS records to propagate, this can lead to premature exit.

fix

Use the `--wait-for-dns` CLI parameter or set `waitForDns: true` in the API options to instruct `wait-port` to continue waiting even if the address is not initially resolvable.

affects: all

gotchaThe CLI uses specific exit codes (0, 1, 2, 3, 4) for different outcomes (success, timeout, unknown error, address not found, invalid target). These are specific to the CLI and not direct JavaScript errors from the API.

fix

When using the CLI in scripts, ensure you check the process exit code for robust error handling. For the API, catch exceptions and check the `open` property of the returned object.

affects: all

Errors

Common errors & fixes

wait-port: Exit code 1

The `wait-port` CLI command timed out before the target port became available.

fix

Increase the timeout duration using the `-t <milliseconds>` flag (e.g., `wait-port -t 30000 localhost:3000`) or ensure the target service is actually starting within a reasonable timeframe.

wait-port: Exit code 3

The address specified for the target could not be found (e.g., DNS resolution failed, or host is unreachable).

fix

Verify the hostname/IP address. If waiting for DNS propagation, use `wait-port --wait-for-dns <target>` to make it retry DNS resolution.

TypeError: waitPort is not a function

Incorrect import statement used for the `waitPort` function, typically trying to use a named import for a default export in ESM or accessing a property on the `require`'d module in CJS.

fix

For ESM, use `import waitPort from 'wait-port';`. For CommonJS, use `const waitPort = require('wait-port');`.

An unknown error occured while waiting for the port: [Error message from catch block]

A generic error occurred during the port check in the programmatic API, often due to invalid parameters or unexpected network conditions not explicitly handled by `wait-port`'s internal logic.

fix

Review the error message for details. Ensure `host` and `port` parameters are valid. Check network connectivity and firewall rules. Increase verbosity if possible (though `wait-port` itself doesn't have a verbose mode for the API beyond `output: 'dots'`).

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dwmkerr/wait-port ↗

packagehttps://www.npmjs.com/package/wait-port ↗