{"id":12648,"library":"wait-port","title":"wait-port: Network Port Availability Utility","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/dwmkerr/wait-port","tags":["javascript"],"install":[{"cmd":"npm install wait-port","lang":"bash","label":"npm"},{"cmd":"yarn add wait-port","lang":"bash","label":"yarn"},{"cmd":"pnpm add wait-port","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary API function is a default export. Use default import for ESM.","wrong":"import { waitPort } from 'wait-port';","symbol":"waitPort","correct":"import waitPort from 'wait-port';"},{"note":"In CommonJS, the package's main function is directly exported.","wrong":"const waitPort = require('wait-port').waitPort;","symbol":"waitPort (CommonJS)","correct":"const waitPort = require('wait-port');"},{"note":"When installed globally, `wait-port` command is available. Locally, use `./node_modules/.bin/wait-port`.","symbol":"CLI Usage","correct":"wait-port localhost:8080 -t 5000"}],"quickstart":{"code":"import waitPort from 'wait-port';\n\nasync function waitForMyService() {\n  console.log('Attempting to connect to example.com:443...');\n  try {\n    const params = {\n      host: 'example.com',\n      port: 443,\n      timeout: 15000, // 15 seconds timeout\n      output: 'dots' // Show progress dots\n    };\n\n    const { open, ipVersion } = await waitPort(params);\n\n    if (open) {\n      console.log(`Successfully connected to example.com:443 on IPv${ipVersion}!`);\n      // Proceed with application logic\n    } else {\n      console.log('Failed to connect to example.com:443 within the timeout period.');\n      process.exit(1);\n    }\n  } catch (error) {\n    console.error(`An unexpected error occurred: ${error.message}`);\n    process.exit(2);\n  }\n}\n\nwaitForMyService();","lang":"typescript","description":"Demonstrates programmatic use of `wait-port` to check for a port's availability with a timeout and handles both success and failure."},"warnings":[{"fix":"Update your code to destructure the returned object, e.g., `const { open, ipVersion } = await waitPort(params);` and check `open` for status.","message":"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 }`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to version 0.2.14 for compatibility with Node 8, or 0.3.0/higher for Node 10+ compatibility.","message":"Version 0.2.13 incorrectly included a breaking change and should be avoided.","severity":"gotcha","affected_versions":"0.2.13"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `wait-port` CLI command timed out before the target port became available.","error":"wait-port: Exit code 1"},{"fix":"Verify the hostname/IP address. If waiting for DNS propagation, use `wait-port --wait-for-dns <target>` to make it retry DNS resolution.","cause":"The address specified for the target could not be found (e.g., DNS resolution failed, or host is unreachable).","error":"wait-port: Exit code 3"},{"fix":"For ESM, use `import waitPort from 'wait-port';`. For CommonJS, use `const waitPort = require('wait-port');`.","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.","error":"TypeError: waitPort is not a function"},{"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'`).","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.","error":"An unknown error occured while waiting for the port: [Error message from catch block]"}],"ecosystem":"npm"}