Advanced

Error Handling & Recovery

Handle typed errors and implement recovery patterns.

This guide covers Hoshimi's error classes, typed error handling, and patterns for graceful recovery.

Typed Error Handling

Use instanceof checks to handle different error categories appropriately.

error-handling.ts
import {
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
} from 'hoshimi';

try {
  // Any Hoshimi operation that may fail
} catch () {
  if ( instanceof ) {
    .('Invalid options:', .);
  } else if ( instanceof ) {
    .('Manager state error:', .);
  } else if ( instanceof ) {
    .('Node connection error:', .);
  } else if ( instanceof ) {
    .('No node available:', .);
  } else if ( instanceof ) {
    .('Queue state error:', .);
  } else if ( instanceof ) {
    .('Playback error:', .);
  } else if ( instanceof ) {
    .('Track resolution failed:', .);
  } else if ( instanceof ) {
    .('Lavalink REST error:', .);
  } else if ( instanceof ) {
    .('Storage adapter error:', .);
  } else {
    .('Unknown error:', );
  }
}

Error Categories

Error TypeCauseRecovery
OptionErrorInvalid configurationFix options, restart
ManagerErrorInvalid manager stateCheck manager initialization
NodeErrorNode connection/statusRetry, fallback to another node
PlayerErrorInvalid player operationValidate player state
ResolveErrorTrack lookup failedTry different search query
RestErrorLavalink HTTP errorRetry with backoff
StorageErrorAdapter operation failedCheck storage backend
NodeManagerErrorNo connected node to pickWait for a node, or add one
QueueErrorQueue holds something that is not a trackInspect what was pushed into it
MergeErrorA required manager option is missingFix the options object

RestError carries the Lavalink response: status, error, path and trace alongside message. NodeError names the node in error.name, so logs point at the right one in a multi-node fleet.

Recovery Checklist

Apply these patterns to ensure resilient playback:

  • Before commands: Check manager.isUsable() for quick health validation.
  • Before player operations: Verify voice channel access and player existence.
  • Queue operations: Guard with queue.isEmpty() before shifting/accessing.
  • Session persistence: Save player/queue state after successful updates.
  • Cleanup: On QueueEnd and PlayerDestroy, clear transient storage (lyrics IDs, message refs).