Multicast DNS (mDNS) Implementation

Common errors

• Error: bind EADDRINUSE 224.0.0.251:5353

  cause Another process (e.g., a system mDNS responder like Bonjour or Avahi, or another instance of `multicast-dns`) is already listening on the default mDNS port and multicast address.
  fix Stop the conflicting process, or configure your `multicast-dns` instance to bind to a specific `interface` if available, or a different `port` (which will prevent standard mDNS discovery for that instance).

• Error: bind EADDRNOTAVAIL

  cause The specified network `interface` in the options (e.g., `interface: '192.168.0.2'`) does not exist or is not available on the current system.
  fix Verify the IP address configured for the `interface` option is correct and corresponds to an active network interface on your machine. Remove the `interface` option to let `multicast-dns` bind to all available interfaces (default behavior).

• TypeError: multicastdns is not a function

  cause The imported/required `multicast-dns` module was not invoked as a function to create an instance. For example, `const mdns = require('multicast-dns');` instead of `const mdns = require('multicast-dns')();`.
  fix Ensure you are calling the imported module as a function: `const mdns = require('multicast-dns')();` for CommonJS, or `const mdns = createMdns();` after `import createMdns from 'multicast-dns';` for ESM.

Warnings

• gotcha The `reuseAddr` option for the underlying UDP socket requires Node.js version 0.11.13 or newer. Using it on older versions will result in an error or unexpected behavior.
  Fix: Ensure your Node.js runtime is updated to a modern version (LTS recommended) or avoid using the `reuseAddr: true` option.
• gotcha The mDNS protocol operates over UDP port 5353, which is a well-known port. Firewalls or other services (like Bonjour/Avahi daemons) might block access or already be using this port, leading to `EADDRINUSE` or `EACCES` errors when binding the socket.
  Fix: Ensure port 5353 is open in your firewall for UDP traffic, or configure a different `port` option (though this would break standard mDNS discovery). If another service is listening, stop it or configure `multicast-dns` to use a different `interface` if available.
• gotcha The README and examples primarily demonstrate CommonJS (`require()`) usage. While modern Node.js supports ESM, careful consideration is needed for `import` statements, especially when the package exports a factory function that needs to be invoked immediately.
  Fix: For ESM, use `import createMdns from 'multicast-dns'; const mdns = createMdns();`. Avoid named imports like `{ mdns }` unless explicitly documented, as the default export is a function.

Install

• npm install multicast-dns npm
• yarn add multicast-dns yarn
• pnpm add multicast-dns pnpm

Imports

• mdns instance (CommonJS)
  wrong:

  const mdns = require('multicast-dns');

  correct:

  const mdns = require('multicast-dns')();

  The `multicast-dns` package exports a factory function that must be immediately invoked to create an mDNS instance.
• mdns instance (ESM)
  wrong:

  import { mdns } from 'multicast-dns';

  correct:

  import createMdns from 'multicast-dns';
  const mdns = createMdns();

  For ESM, import the default export (the factory function) and then call it to get a new mDNS instance. The package's primary documentation showcases CommonJS usage.
• Packet Types (TypeScript)
  wrong:

  import { Packet } from 'multicast-dns';

  correct:

  import type { Packet, Question, Answer } from 'multicast-dns';

  While the library is JavaScript, TypeScript type definitions are often available via `@types/multicast-dns` for enhanced development experience. Common types include `Packet`, `Question`, and `Answer` for handling mDNS data structures.

Quickstart

This quickstart initializes a `multicast-dns` instance, logs incoming query and response packets, demonstrates how to query for specific records, and how to respond to queries for a known service, then destroys the instance.

import createMdns from 'multicast-dns';

const mdns = createMdns();

mdns.on('response', function(response) {
  console.log('Got a mDNS response packet:', JSON.stringify(response, null, 2));
});

mdns.on('query', function(query) {
  console.log('Got a mDNS query packet:', JSON.stringify(query, null, 2));
  // Example: Respond to a query for 'my-service.local'
  if (query.questions[0] && query.questions[0].name === 'my-service.local') {
    mdns.respond({
      answers: [{
        name: 'my-service.local',
        type: 'A',
        ttl: 120,
        data: '127.0.0.1' // Replace with actual IP
      }]
    });
    console.log('Responded to query for my-service.local');
  }
});

// Query for an A record for a local hostname (e.g., your-hostname.local)
mdns.query({
  questions:[
    {
      name: 'your-hostname.local',
      type: 'A'
    },
    {
      name: 'my-service.local',
      type: 'SRV'
    }
  ]
});

console.log('Sent mDNS query for your-hostname.local and my-service.local');

// Destroy the instance after a timeout to prevent resource leaks in short-lived scripts
setTimeout(() => {
  mdns.destroy();
  console.log('mDNS instance destroyed.');
}, 10000);