XML-RPC Client and Server

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax to load the CommonJS-only `xmlrpc` package.
  fix Change your import statement to `const xmlrpc = require('xmlrpc');`.

• Method 'yourMethodName' does not exist

  cause The XML-RPC server received a method call for which no corresponding event listener was registered using `server.on('methodName', ...)`.
  fix Ensure that `server.on('methodName', function(err, params, callback){...})` is defined for every method the server is expected to handle. Implement a `server.on('NotFound', ...)` handler for debugging unhandled method calls.

• Date/Time format mismatch or parsing errors in XML-RPC communication.

  cause The default ISO 8601 date formatting used by `xmlrpc` for encoding does not match the specific variant expected by the receiving XML-RPC endpoint, or vice-versa.
  fix Use `xmlrpc.dateFormatter.setOpts(options)` to precisely configure the date encoding options (e.g., `colons`, `hyphens`, `local`, `ms`, `offset`) to match the requirements of your XML-RPC communication partners.

Warnings

• gotcha The `xmlrpc` package has not been updated since June 2016 (v1.3.2). This signifies a lack of active maintenance, posing compatibility risks with modern Node.js versions (e.g., ESM, current HTTP standards), potential unpatched security vulnerabilities in its own code or its `sax` and `xmlbuilder` dependencies, and general instability when integrated into contemporary applications.
  Fix: Evaluate actively maintained alternatives for XML-RPC communication or thoroughly audit the code and its dependencies for security and compatibility issues if you must use this package. Consider using a compatibility layer for CommonJS in ESM projects.
• breaking Support for Node.js v0.8 was explicitly dropped in version 1.3.2. Applications running on very old Node.js environments may encounter issues or require a downgrade to an earlier `xmlrpc` version.
  Fix: Upgrade your Node.js runtime to a more recent, supported version (e.g., Node.js v6.x or newer as supported by the last release).
• gotcha This package is a CommonJS module and does not natively support ES module `import` syntax. Attempting to use `import xmlrpc from 'xmlrpc'` in a pure ESM context will result in a runtime error.
  Fix: Always use `const xmlrpc = require('xmlrpc');` for importing the module. If working in an ESM-only project, you might need to use a bundler or a wrapper to consume CommonJS modules.
• gotcha The underlying XML builder library (`xmlbuilder`) saw significant version updates across `xmlrpc` releases (e.g., v2.4 to v8.2). While `xmlrpc` aims to abstract this, large jumps in internal dependency versions can sometimes introduce subtle changes in XML output or parsing behavior, particularly with edge cases.
  Fix: Thoroughly test XML payloads and parsing logic when upgrading `xmlrpc` across major minor versions to ensure consistent behavior, especially if you rely on specific XML structuring or attribute ordering.

Install

• npm install xmlrpc npm
• yarn add xmlrpc yarn
• pnpm add xmlrpc pnpm

Imports

• xmlrpc
  wrong:

  import xmlrpc from 'xmlrpc'

  correct:

  const xmlrpc = require('xmlrpc')

  This package is CommonJS-only. Direct ES module `import` syntax will fail.
• createServer
  wrong:

  import { createServer } from 'xmlrpc'

  correct:

  const server = xmlrpc.createServer({ host: 'localhost', port: 9090 })

  Accessed as a method of the default `xmlrpc` export; not a named export.
• createClient
  wrong:

  import { createClient } from 'xmlrpc'

  correct:

  const client = xmlrpc.createClient({ host: 'localhost', port: 9090, path: '/' })

  Accessed as a method of the default `xmlrpc` export; not a named export.

Quickstart

This example demonstrates how to set up both an XML-RPC server and client, allowing them to communicate locally. It registers a server method 'anAction' and then uses the client to invoke it, showcasing basic call and response patterns.

const xmlrpc = require('xmlrpc');

// Creates an XML-RPC server to listen to XML-RPC method calls
const server = xmlrpc.createServer({ host: 'localhost', port: 9090 });

// Handle methods not found
server.on('NotFound', function(method, params) {
  console.log('Method ' + method + ' does not exist');
});

// Handle method calls by listening for events with the method call name
server.on('anAction', function (err, params, callback) {
  console.log('Method call params for \'anAction\': ' + params);

  // ...perform an action...

  // Send a method response with a value
  callback(null, 'aResult');
});
console.log('XML-RPC server listening on port 9090');

// Waits briefly to give the XML-RPC server time to start up and start
// listening
setTimeout(function () {
  // Creates an XML-RPC client. Passes the host information on where to
  // make the XML-RPC calls.
  const client = xmlrpc.createClient({ host: 'localhost', port: 9090, path: '/'});

  // Sends a method call to the XML-RPC server
  client.methodCall('anAction', ['aParam'], function (error, value) {
    // Results of the method response
    console.log('Method response for \'anAction\': ' + value);
  });

}, 1000);