Free WHOIS Node.js Client

Common errors

• TypeError: whois is not a function

  cause Attempting to call `whois` after importing it incorrectly, e.g., using `import { whois } from 'freewhois';` when it's a default export.
  fix For ESM, use `import whois from 'freewhois';`. For CommonJS, use `const whois = require('freewhois');`.

• Error: ENOTFOUND <hostname>

  cause The domain name provided is either syntactically invalid, or the DNS lookup for the corresponding RDAP server failed.
  fix Verify the spelling and format of the domain name. Check your network's DNS resolution, and ensure the domain's TLD is recognized and has an active RDAP service.

• Error: Domain not found for <domain>

  cause The provided domain name is valid but does not exist or is not registered.
  fix This is expected behavior for unregistered domains. No fix is needed unless you intended to query a registered domain; in that case, double-check the domain's spelling and existence.

Warnings

• gotcha The package relies on a list of TLDs sourced from iana.org. This list is updated manually. If you are experiencing issues with new TLDs or incorrect lookups, your local TLD list might be outdated.
  Fix: Run `npm run update-tlds` in your project directory (if installed locally) or manually update the package if installed globally, to refresh the TLD data.
• gotcha WHOIS lookups involve external network requests to various RDAP servers. Network connectivity issues, DNS resolution problems, or temporary unavailability of specific RDAP servers can cause lookups to fail.
  Fix: Implement robust error handling around your `whois` calls and consider retries for transient network failures. Ensure your network configuration allows outbound connections to RDAP servers.
• gotcha While `freewhois` uses IANA RDAP for 'free' lookups, aggressive querying (e.g., thousands of requests per second) can still lead to temporary IP blocking or rate limiting by the individual TLD's RDAP servers.
  Fix: Introduce sensible delays or rate limiting in your application if performing a high volume of lookups. Cache results where appropriate to reduce redundant requests.

Install

• npm install freewhois npm
• yarn add freewhois yarn
• pnpm add freewhois pnpm

Imports

• whois
  wrong:

  import whois from 'freewhois';

  correct:

  const whois = require('freewhois');

  This package primarily targets CommonJS environments as shown in its README, though ESM import should work with proper configuration.
• whois
  wrong:

  import { whois } from 'freewhois';

  correct:

  import whois from 'freewhois';

  The main function is exported as a default export, not a named one. Using named import will result in 'undefined' or a runtime error.
• freewhois CLI

  npm i freewhois -g
  freewhois "google.com"

  For command-line usage, install globally. The CLI acts as a wrapper for the programmatic API.

Quickstart

Demonstrates how to perform a WHOIS lookup for a domain and handle potential errors using the async/await pattern.

const whois = require('freewhois');

async function performWhoisLookup(domain) {
    try {
        console.log(`
Looking up WHOIS for: ${domain}`);
        const data = await whois(domain);
        console.log(`WHOIS data for ${domain}:`);
        console.log(JSON.stringify(data, null, 2));
    } catch (error) {
        console.error(`Error looking up WHOIS for ${domain}:`, error.message);
        if (error.response && error.response.status) {
            console.error(`HTTP Status: ${error.response.status}`);
        }
    }
}

// Example usage for a well-known domain
performWhoisLookup('google.com');

// Example for a common TLD
performWhoisLookup('example.com');

// Example for a domain that likely does not exist, to demonstrate error handling
performWhoisLookup('nonexistent-domain-1234567890.xyz');