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.
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 Type | Cause | Recovery |
|---|---|---|
| OptionError | Invalid configuration | Fix options, restart |
| ManagerError | Invalid manager state | Check manager initialization |
| NodeError | Node connection/status | Retry, fallback to another node |
| PlayerError | Invalid player operation | Validate player state |
| ResolveError | Track lookup failed | Try different search query |
| RestError | Lavalink HTTP error | Retry with backoff |
| StorageError | Adapter operation failed | Check storage backend |
| NodeManagerError | No connected node to pick | Wait for a node, or add one |
| QueueError | Queue holds something that is not a track | Inspect what was pushed into it |
| MergeError | A required manager option is missing | Fix 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
QueueEndandPlayerDestroy, clear transient storage (lyrics IDs, message refs).