Minecraft RCON Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'send')

  cause Attempting to call `send()` on an `Rcon` instance that has not yet successfully connected, or after it has been explicitly `end()`ed, or if `await Rcon.connect()` was forgotten.
  fix Ensure `await rcon.connect()` completes successfully before calling `rcon.send()`. If using the static `Rcon.connect()`, ensure you `await` its result. Check connection status via events (`connect`, `end`, `error`) if managing connection state manually.

• Error: RCON connection failed: Authentication failed.

  cause The provided password for the RCON server is incorrect.
  fix Verify the RCON password configured on your Minecraft server and ensure it matches the `password` field in your `Rcon.connect()` options. Double-check for typos or leading/trailing spaces.

• Error: connect ECONNREFUSED

  cause The RCON client was unable to establish a TCP connection to the specified host and port. This usually means the server is not running, RCON is not enabled, or a firewall is blocking the connection.
  fix 1. Ensure your Minecraft server is running. 2. Verify that RCON is enabled in your server's `server.properties` (`enable-rcon=true`). 3. Check the `rcon.port` and `rcon.password` in `server.properties`. 4. Confirm no firewall (OS or network) is blocking connections to the RCON port on the server host. 5. Double-check the `host` and `port` values in your `Rcon.connect()` call.

Warnings

• deprecated The `rcon-client` library is no longer actively maintained. The maintainer explicitly states this in the README, advising caution or considering alternative implementations. This means bug fixes, security updates, and new features are unlikely to be released.
  Fix: For new projects, evaluate more actively maintained RCON client libraries. If already using, be aware of potential unaddressed issues and consider contributing to the project or forking it if critical updates are needed.
• gotcha Improper handling of connection state: The `Rcon` instance supports connecting and disconnecting at any time. However, attempting to send commands on a disconnected Rcon instance will result in errors. Always ensure the client is connected before sending commands.
  Fix: Use the `connect()` method before `send()`, and consider implementing an auto-reconnect logic using the exposed events (`connect`, `end`, `error`) if your application requires resilient connections. The `connect` method can be called multiple times on the same instance after calling `end`.
• gotcha Forgotten `await` for asynchronous operations. All network operations (`Rcon.connect`, `rcon.send`) return Promises and must be awaited to correctly handle their results and prevent unhandled promise rejections.
  Fix: Always use `await` before `Rcon.connect(...)` and `rcon.send(...)`. Wrap asynchronous calls in a `try...catch` block to gracefully handle potential connection or command execution errors.

Install

• npm install rcon-client npm
• yarn add rcon-client yarn
• pnpm add rcon-client pnpm

Imports

• Rcon
  wrong:

  const Rcon = require('rcon-client')

  correct:

  import { Rcon } from 'rcon-client'

  The library primarily targets modern JavaScript environments and TypeScript, preferring ES module syntax. While CommonJS might work via transpilation or older Node versions, direct `require` is not the idiomatic usage.
• Rcon.connect
  wrong:

  const rcon = Rcon.connect({ host: 'localhost', port: 25575, password: '1234' })

  correct:

  const rcon = await Rcon.connect({ host: 'localhost', port: 25575, password: '1234' })

  The `connect` static method is asynchronous and returns a Promise, so it must be awaited to get the `Rcon` instance. Forgetting `await` will result in a Promise object instead of the connected Rcon client.
• RconEvents

  import type { RconEvents } from 'rcon-client'

  To type-hint event handlers for the `Rcon` instance's event emitter, import `RconEvents` as a type. This is useful for implementing custom event listeners with strong typing.

Quickstart

This quickstart demonstrates how to establish an RCON connection using the static `connect` method, send a single command, execute multiple commands concurrently using `Promise.all`, and properly close the connection. It includes basic error handling and uses environment variables for sensitive connection details.

import { Rcon } from "rcon-client";

async function runRconCommands() {
    console.log('Attempting to connect to RCON server...');
    try {
        const rcon = await Rcon.connect({
            host: process.env.RCON_HOST ?? 'localhost',
            port: parseInt(process.env.RCON_PORT ?? '25575'),
            password: process.env.RCON_PASSWORD ?? '1234'
        });
        console.log('Connected to RCON server.');

        console.log('Sending \"list\" command...');
        const listResponse = await rcon.send("list");
        console.log('Response from \"list\":', listResponse);

        console.log('Sending \"help\" and \"whitelist list\" concurrently...');
        let responses = await Promise.all([
            rcon.send("help"),
            rcon.send("whitelist list")
        ]);

        console.log('Responses from concurrent commands:');
        for (const response of responses) {
            console.log(response);
        }

        rcon.end();
        console.log('RCON connection ended.');
    } catch (error) {
        console.error('Failed to connect or send RCON command:', error);
    }
}

runRconCommands();