Steam Master and Game Server Query

Common errors

• Error: Request timed out

  cause The queried game or master server did not respond within the specified timeout duration, or the server is offline/unreachable.
  fix Increase the `timeout` parameter for the query function. Verify the `gameServer` address and port are correct and that the server is online and accessible from your network. Check firewall rules.

• TypeError: queryMasterServer is not a function

  cause This typically occurs in CommonJS environments (Node.js without type: 'module' in package.json) when trying to use ES module `import` syntax or an incorrect `require` pattern.
  fix For CommonJS, use `const { queryMasterServer, REGIONS } = require('steam-server-query');`. Ensure your project's `package.json` is not explicitly set to `"type": "module"` if you intend to use `require`.

• Error: Address already in use

  cause This error can occur when a UDP socket tries to bind to a port that is still in use, often due to improper socket closure in previous operations.
  fix This issue was largely resolved in `steam-server-query@1.1.1`. Ensure you are on version `1.1.1` or higher. If the problem persists, it may indicate another application is using the port, or a very rapid succession of queries without allowing the OS to release the port.

Warnings

• gotcha Older versions of the library (prior to v1.1.1) had issues with UDP sockets not closing correctly after a request, leading to potential resource leaks or 'address already in use' errors. This was resolved in v1.1.1.
  Fix: Upgrade to `steam-server-query@1.1.1` or newer to ensure proper socket cleanup.
• gotcha Master server queries can be rate-limited by Valve's servers if too many requests are made in a short period. The `maxHosts` option was introduced to help mitigate this by limiting the number of hosts returned.
  Fix: When calling `queryMasterServer`, utilize the `maxHosts` parameter to cap the number of returned servers, e.g., `queryMasterServer(..., maxHosts: 50)`. Consider adding delays between successive master server queries if fetching large lists.
• gotcha A2S_PLAYER requests may sometimes require multiple attempts or 'challenge retries' due to the protocol specifics, which could lead to initial failures. This was addressed with an internal fix in v1.1.3.
  Fix: Upgrade to `steam-server-query@1.1.3` or newer. If on an older version, manually implement retry logic when calling `queryGameServerPlayer`.
• gotcha Game server query functions (`queryGameServerInfo`, `queryGameServerPlayer`, `queryGameServerRules`) expect the `gameServer` argument in `host:port` format. Providing just a hostname or an IP without a port will result in connection failures.
  Fix: Always ensure the `gameServer` string includes both the host (IP or domain) and the port, e.g., `'192.168.1.100:27015'` or `'mygameserver.com:27015'`.

Install

• npm install steam-server-query npm
• yarn add steam-server-query yarn
• pnpm add steam-server-query pnpm

Imports

• queryMasterServer
  wrong:

  const { queryMasterServer } = require('steam-server-query');

  correct:

  import { queryMasterServer } from 'steam-server-query';

  The library primarily uses named exports. Prefer ES Modules.
• queryGameServerInfo
  wrong:

  import queryGameServerInfo from 'steam-server-query';

  correct:

  import { queryGameServerInfo } from 'steam-server-query';

  All main query functions are named exports.
• REGIONS
  wrong:

  import * as REGIONS from 'steam-server-query';

  correct:

  import { REGIONS } from 'steam-server-query';

  REGIONS is an enum and should be imported as a named export.
• Filter

  import type { Filter } from 'steam-server-query';

  Import types using 'import type' for clarity and tree-shaking benefits in TypeScript.

Quickstart

Demonstrates querying a Steam master server to find Team Fortress 2 servers, then querying the first found game server for its detailed information and player list.

import { queryMasterServer, queryGameServerInfo, queryGameServerPlayer, REGIONS } from 'steam-server-query';

async function runQuery() {
  try {
    console.log('Querying master server for all regions...');
    const masterServers = [
      'hl2master.steampowered.com:27011',
      'hl2master.steampowered.com:27012'
    ];

    const gameServers = await queryMasterServer(masterServers[0], REGIONS.ALL, {
      appid: 440, // Team Fortress 2
      gamedir: 'tf',
      empty: 1
    }, 2000, 5); // Timeout 2s, max 5 hosts

    if (gameServers.length === 0) {
      console.log('No game servers found matching criteria.');
      return;
    }

    console.log(`Found ${gameServers.length} game servers. Querying the first one: ${gameServers[0]}`);

    const serverInfo = await queryGameServerInfo(gameServers[0]);
    console.log('\n--- Server Info ---');
    console.log(`Name: ${serverInfo.name}`);
    console.log(`Map: ${serverInfo.map}`);
    console.log(`Players: ${serverInfo.players}/${serverInfo.maxPlayers}`);
    console.log(`Game: ${serverInfo.game}`);

    const playerInfo = await queryGameServerPlayer(gameServers[0]);
    console.log('\n--- Player Info ---');
    playerInfo.players.forEach(player => {
      console.log(`- ${player.name} (Score: ${player.score}, Duration: ${player.duration.toFixed(2)}s)`);
    });

    // Example of handling potential errors or missing player data
    if (playerInfo.players.length === 0) {
      console.log('No players found on this server.');
    }

  } catch (error) {
    console.error('An error occurred during the query:', error.message);
    if (error.code === 'ETIMEDOUT') {
      console.error('The server query timed out. The server might be offline or unreachable.');
    }
  }
}

runQuery();