{"id":17231,"library":"freewhois","title":"Free WHOIS Node.js Client","description":"freewhois is a Node.js client designed for retrieving WHOIS information by querying the IANA RDAP DNS database. It provides a free and programmatic way to perform domain lookups. The current stable version is 1.3.8. While a specific release cadence isn't detailed, the TLD list is noted as being updated regularly (last on 11/2/2025), suggesting ongoing maintenance. Its key differentiator is leveraging the IANA RDAP database directly, offering a straightforward, free API for WHOIS queries without relying on external, potentially rate-limited, third-party services. It supports both programmatic use in JavaScript/TypeScript projects and includes a command-line interface for quick lookups, making it versatile for both developers and system administrators.","status":"active","version":"1.3.8","language":"javascript","source_language":"en","source_url":"https://github.com/joshterrill/freewhois","tags":["javascript","whois","dns","free whois","dns lookup","reverse lookup","reverse dns","ip lookup","reverse ip"],"install":[{"cmd":"npm install freewhois","lang":"bash","label":"npm"},{"cmd":"yarn add freewhois","lang":"bash","label":"yarn"},{"cmd":"pnpm add freewhois","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package primarily targets CommonJS environments as shown in its README, though ESM import should work with proper configuration.","wrong":"import whois from 'freewhois';","symbol":"whois","correct":"const whois = require('freewhois');"},{"note":"The main function is exported as a default export, not a named one. Using named import will result in 'undefined' or a runtime error.","wrong":"import { whois } from 'freewhois';","symbol":"whois","correct":"import whois from 'freewhois';"},{"note":"For command-line usage, install globally. The CLI acts as a wrapper for the programmatic API.","symbol":"freewhois CLI","correct":"npm i freewhois -g\nfreewhois \"google.com\""}],"quickstart":{"code":"const whois = require('freewhois');\n\nasync function performWhoisLookup(domain) {\n    try {\n        console.log(`\nLooking up WHOIS for: ${domain}`);\n        const data = await whois(domain);\n        console.log(`WHOIS data for ${domain}:`);\n        console.log(JSON.stringify(data, null, 2));\n    } catch (error) {\n        console.error(`Error looking up WHOIS for ${domain}:`, error.message);\n        if (error.response && error.response.status) {\n            console.error(`HTTP Status: ${error.response.status}`);\n        }\n    }\n}\n\n// Example usage for a well-known domain\nperformWhoisLookup('google.com');\n\n// Example for a common TLD\nperformWhoisLookup('example.com');\n\n// Example for a domain that likely does not exist, to demonstrate error handling\nperformWhoisLookup('nonexistent-domain-1234567890.xyz');","lang":"javascript","description":"Demonstrates how to perform a WHOIS lookup for a domain and handle potential errors using the async/await pattern."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ESM, use `import whois from 'freewhois';`. For CommonJS, use `const whois = require('freewhois');`.","cause":"Attempting to call `whois` after importing it incorrectly, e.g., using `import { whois } from 'freewhois';` when it's a default export.","error":"TypeError: whois is not a function"},{"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.","cause":"The domain name provided is either syntactically invalid, or the DNS lookup for the corresponding RDAP server failed.","error":"Error: ENOTFOUND <hostname>"},{"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.","cause":"The provided domain name is valid but does not exist or is not registered.","error":"Error: Domain not found for <domain>"}],"ecosystem":"npm","meta_description":null}