Errors

The player uses a structured error hierarchy. All errors carry a string code, a severity, and a human-readable message. Catching by code or by class is always preferred over catching raw Error.

Error classes

All classes are exported from @nomercy-entertainment/nomercy-player-core@beta.

Error codes

Code format: <vendor>:<category>/<detail>.

Core codes always start with core:. Plugin codes are namespaced with the plugin id, e.g. equalizer:band/out-of-range.

Auth errors (AuthError)

Network errors (NetworkError)

Stream errors (StreamError)

Media format errors (MediaFormatError)

Resource errors (ResourceError)

Browser policy errors (BrowserPolicyError)

There is a core:policy/<capability>Unsupported (or Unavailable) code for each gated browser capability — AirPlay, Web Audio, canvas 2D, capture-stream, IndexedDB, remote playback, wake lock, setSinkId, and the audio-output picker among them.

Playlist errors (PlayerError)

Plugin errors (PluginError)

Not-implemented errors (NotImplementedError)

Severity tiers

Listening to errors

player.on('error', (event) => {
  console.error(`Error ${event.error.code}: ${event.error.message}`);
});

player.on('fatal', () => {
  showUserMessage('Playback failed. Please reload.');
});

player.on('warning', (event) => {
  console.warn(`Warning ${event.error.code}: ${event.error.message}`);
});

The handler receives a PlayerErrorEvent. The structured error lives on .error (so it is event.error.code, not event.code); the rest of the payload is the severity, scope, timestamp, and the cancellable-event controls:

interface PlayerErrorEvent {
  error: PlayerError;        // .code, .message, .cause?, .context?, .suggestion?
  severity: 'fatal' | 'error' | 'warning' | 'info';
  scope: ErrorScope;
  timestamp: number;

  markHandled(): void;
  isHandled(): boolean;
  stopImmediatePropagation(): void;
  isPropagationStopped(): boolean;
  preventDefault(): void;       // suppress the kit's default action (e.g. auto-retry)
  isDefaultPrevented(): boolean;
}

NotImplementedError

NotImplementedError is thrown when a method exists in the public contract but the current backend or library does not support it.

Known cases in v2.0:

• player.subtitles() on NMMusicPlayer: audio backends have no subtitle tracks
• GroupListeningPlugin, DrmPlugin, LiveTranscodingPlugin on NMMusicPlayer: these throw NotImplementedError in their use() (planned for v2.1)

Catch by class, not by message:

import { NotImplementedError } from '@nomercy-entertainment/nomercy-player-core';

try {
  const tracks = player.subtitles();
} catch (error) {
  if (error instanceof NotImplementedError) {
    // expected: audio player doesn't have subtitle tracks
  } else {
    throw error; // re-throw unexpected errors
  }
}

Code always follows core:not-implemented/<feature>.

Static recovery policy

Plugins declare how they respond to specific error codes:

class MyPlugin extends Plugin {
  static readonly onError: Record<string, PluginRecoveryAction> = {
    'core:stream/segment-load-failed': 'retry-once',
    'core:auth/forbidden': 'disable',
    'core:network/timeout': 'ignore',
  };
}

Recovery actions are declared per plugin through static onError; 'retry-once' calls the plugin’s retryLastOperation() and 'fallback' calls its activateFallback(). There is no setup-level override.

Inside plugins: this.throw and this.report

Never throw raw errors or emit error events directly from a plugin. Always use the plugin’s methods:

// Fatal: plugin fails. Player and other plugins continue.
this.throw({
  severity: 'fatal',
  code: 'nomercy:sync/connection-lost',
  message: 'Lost connection to sync server',
});

// Non-fatal: operation fails. Plugin keeps running.
this.throw({
  severity: 'error',
  code: 'nomercy:sync/fetch-failed',
  message: 'Sync fetch returned an error',
});

// Warning / info: observability. No action needed.
this.report({
  severity: 'warning',
  code: 'nomercy:sync/rate-limited',
  message: 'Sync endpoint rate-limited, will retry in 30s',
});

Errors thrown with this.throw are caught, wrapped in PluginError, emitted via the player’s event bus, and if severity is 'fatal', the plugin is marked failed. Other plugins always continue.