Overview

A network partition, a server that hasn't started yet, or a typo in the address are all normal facts of life in distributed systems — and a client that blocks indefinitely or throws an opaque error turns a routine outage into a cascading failure. Fail-fast connection checking lets you detect an unreachable KubeMQ server the moment you call KubeMQClient.create(), bounded by connectionTimeoutSeconds, so your service can log the failure, alert, or fall back instead of hanging.

create() throws a typed ConnectionError (or KubeMQTimeoutError once the timeout elapses) instead of hanging forever, and a separate ConfigurationError when the options are invalid — before any network I/O happens. All SDK errors extend the base KubeMQError, so err.code gives you the machine-readable error code and err.isRetryable tells you whether attempting again is worthwhile. Gotchas: check the specific subclass (ConnectionError vs ConfigurationError vs AuthenticationError) before the generic KubeMQError branch, or you lose the actionable err.suggestion; isRetryable reflects the failure category, not your retry budget — retrying an unreachable server in a tight loop just multiplies the outage; a successful create() doesn't guarantee the connection stays up, so mid-session drops still need reconnection handling.

Prerequisites

KubeMQ server running on localhost:50000
Node.js SDK installed (npm install kubemq-js)

Code

connection-error.ts

/**
 * Example: Connection Error Handling
 *
 * Demonstrates handling connection errors when the KubeMQ server is
 * unreachable, misconfigured, or requires authentication. Shows how
 * to catch specific error types and provide actionable diagnostics.
 *
 * Prerequisites:
 *   - This example intentionally connects to an invalid address.
 *
 * Run: npx tsx examples/error-handling/connection-error.ts
 */
import {
  KubeMQClient,
  ConnectionError,
  AuthenticationError,
  KubeMQTimeoutError,
  ConfigurationError,
  KubeMQError,
} from 'kubemq-js';

async function main(): Promise<void> {
  // --- Scenario 1: Unreachable server ---
  console.log('=== Scenario 1: Unreachable Server ===');
  try {
    await KubeMQClient.create({
      address: 'localhost:59999',
      clientId: 'js-error-handling-connection-error-client',
      connectionTimeoutSeconds: 3,
    });
  } catch (err) {
    if (err instanceof ConnectionError) {
      console.log('ConnectionError caught:', err.message);
      console.log('  Error code:', err.code);
      console.log('  Is retryable:', err.isRetryable);
      if (err.suggestion) {
        console.log('  Suggestion:', err.suggestion);
      }
    } else if (err instanceof KubeMQTimeoutError) {
      console.log('TimeoutError: Server did not respond within 3 seconds');
    } else {
      console.log('Unexpected error:', (err as Error).message);
    }
  }

  // --- Scenario 2: Invalid configuration ---
  console.log('\n=== Scenario 2: Invalid Configuration ===');
  try {
    await KubeMQClient.create({
      address: '',
      clientId: 'js-error-handling-connection-error-invalid-client',
    });
  } catch (err) {
    if (err instanceof ConfigurationError) {
      console.log('ConfigurationError caught:', err.message);
    } else if (err instanceof KubeMQError) {
      console.log('KubeMQError caught:', err.message);
      console.log('  Code:', err.code);
    } else {
      console.log('Unexpected error:', (err as Error).message);
    }
  }

  // --- Scenario 3: Authentication failure ---
  console.log('\n=== Scenario 3: Authentication Failure (simulated) ===');
  try {
    // This will fail at connection level since server is not running,
    // but demonstrates the pattern for catching auth errors.
    await KubeMQClient.create({
      address: 'localhost:59999',
      clientId: 'js-error-handling-connection-error-auth-client',
      credentials: 'invalid-token',
      connectionTimeoutSeconds: 3,
    });
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.log('AuthenticationError: Invalid credentials');
    } else if (err instanceof ConnectionError) {
      console.log('ConnectionError (expected in demo):', err.message);
    } else {
      console.log('Error:', (err as Error).message);
    }
  }

  console.log('\nAll error scenarios demonstrated');
}

main().catch(console.error);

How It Works

Scenario 1 targets port 59999 (nothing listening) with a 3-second connectionTimeoutSeconds — KubeMQClient.create() throws ConnectionError or KubeMQTimeoutError instead of hanging forever.
Scenario 2 passes an empty address string; the SDK's ConfigurationError is thrown before any network I/O, with err.message describing the invalid field.
Scenario 3 shows the pattern for AuthenticationError — it surfaces during create() when the server rejects the token, separate from transport-level connection failures.
All SDK errors extend KubeMQError; check err.code for the machine-readable ErrorCode constant and err.isRetryable to decide whether to retry.

Connection Error

Overview

Prerequisites

Code

How It Works

Related

On this page