wait-port: Network Port Availability Utility

1.1.0 · active · verified Sun Apr 19

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.

Common errors

```
wait-port: Exit code 1
```
cause 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
```
cause 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
```
cause 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]
```
cause 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'`).

Warnings

breaking The 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.
gotcha Version 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.
gotcha When 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.
gotcha The 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.

Install

npm install wait-port npm
yarn add wait-port yarn
pnpm add wait-port pnpm

Imports

waitPort
wrong:
```
import { waitPort } from 'wait-port';
```
correct:
```
import waitPort from 'wait-port';
```
The primary API function is a default export. Use default import for ESM.
waitPort (CommonJS)
wrong:
```
const waitPort = require('wait-port').waitPort;
```
correct:
```
const waitPort = require('wait-port');
```
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`.

Quickstart

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();

view raw JSON →