fix(bot): expose degraded-extractor signal and honest play error

packages/bot/src/functions/music/commands/play/handlers/playErrorMessage.spec.ts

@@ -0,0 +1,53 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const isExtractorDegradedMock = jest.fn(() => false)
+
+jest.mock('../../../../../handlers/player/extractorHealth', () => ({
+    isExtractorDegraded: (...args: unknown[]) =>
+        isExtractorDegradedMock(...args),
+}))
+
+import { resolvePlayErrorMessage } from './playErrorMessage'
+
+describe('resolvePlayErrorMessage', () => {
+    beforeEach(() => {
+        jest.clearAllMocks()
+        isExtractorDegradedMock.mockReturnValue(false)
+    })
+
+    it('reports sources unreachable for a no-results error while youtube is degraded', () => {
+        isExtractorDegradedMock.mockReturnValue(true)
+        const error = new Error(
+            'No results found for "some song" (Extractor: com.discord-player.youtube)',
+        )
+
+        expect(resolvePlayErrorMessage(error)).toBe(
+            'Music sources are currently unreachable. Please try again in a few minutes.',
+        )
+        expect(isExtractorDegradedMock).toHaveBeenCalledWith('youtube')
+    })
+
+    it('falls back to the sanitized message for a no-results error when youtube is healthy', () => {
+        isExtractorDegradedMock.mockReturnValue(false)
+        const error = new Error('No results found for "some song"')
+
+        expect(resolvePlayErrorMessage(error)).toContain('No results found')
+    })
+
+    it('does not override an unrelated error even while youtube is degraded', () => {
+        isExtractorDegradedMock.mockReturnValue(true)
+        const error = new Error('ffmpeg exited unexpectedly')
+
+        expect(resolvePlayErrorMessage(error)).not.toBe(
+            'Music sources are currently unreachable. Please try again in a few minutes.',
+        )
+    })
+
+    it('handles a non-Error thrown value without throwing', () => {
+        isExtractorDegradedMock.mockReturnValue(true)
+
+        expect(() =>
+            resolvePlayErrorMessage('plain string error'),
+        ).not.toThrow()
+    })
+})

packages/bot/src/functions/music/commands/play/handlers/playErrorMessage.ts

@@ -0,0 +1,14 @@
+import { createUserFriendlyError } from '@lucky/shared/utils/general/errorSanitizer'
+import { isExtractorDegraded } from '../../../../../handlers/player/extractorHealth'
+
+// "No results found" is misleading when it's actually a degraded extractor
+// (e.g. YouTube session init silently failed but registration still
+// reported success) — say so instead (#1929).
+export function resolvePlayErrorMessage(error: unknown): string {
+    const isNoResultsError =
+        error instanceof Error && /no results found/i.test(error.message)
+    if (isNoResultsError && isExtractorDegraded('youtube')) {
+        return 'Music sources are currently unreachable. Please try again in a few minutes.'
+    }
+    return createUserFriendlyError(error)
+}

packages/bot/src/functions/music/commands/play/handlers/playHandler.ts

@@ -6,7 +6,6 @@ import { errorLog, debugLog, warnLog } from '@lucky/shared/utils'
 import { assertDefined } from '@lucky/shared/utils/guards'
 import { createErrorEmbed } from '../../../../../utils/general/embeds'
 import { interactionReply } from '../../../../../utils/general/interactionReply'
-import { createUserFriendlyError } from '@lucky/shared/utils/general/errorSanitizer'
 import { collaborativePlaylistService } from '../../../../../services/musicRecommendation/collaborativePlaylist'
 import { moveUserTrackToPriority } from '../../../../../services/musicManagement/queueManipulation'
 import { buildPlayResponseEmbed } from '../../../../../utils/music/nowPlayingEmbed'
@@ -23,6 +22,7 @@ import {
     emitPlayResolutionTelemetry,
 } from './resolveProvider'
 import { runPostPlayBackgroundOps } from './postPlayBackgroundOps'
+import { resolvePlayErrorMessage } from './playErrorMessage'
 
 export async function executePlayHandler({
     client,
@@ -250,7 +250,7 @@ export async function executePlayHandler({
                     embeds: [
                         createErrorEmbed(
                             'Play Error',
-                            createUserFriendlyError(error),
+                            resolvePlayErrorMessage(error),
                         ),
                     ],
                     ephemeral: true,

packages/bot/src/handlers/player/extractorHealth.spec.ts

@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const gaugeSetMock = jest.fn()
+
+jest.mock('../../utils/monitoring/prometheus', () => ({
+    musicExtractorDegradedGauge: {
+        set: (...args: unknown[]) => gaugeSetMock(...args),
+    },
+}))
+
+import { isExtractorDegraded, setExtractorDegraded } from './extractorHealth'
+
+describe('extractorHealth', () => {
+    beforeEach(() => {
+        jest.clearAllMocks()
+        setExtractorDegraded('youtube', false)
+        jest.clearAllMocks()
+    })
+
+    it('reports healthy by default', () => {
+        expect(isExtractorDegraded('youtube')).toBe(false)
+    })
+
+    it('marks an extractor degraded and updates the gauge', () => {
+        setExtractorDegraded('youtube', true)
+
+        expect(isExtractorDegraded('youtube')).toBe(true)
+        expect(gaugeSetMock).toHaveBeenCalledWith({ extractor: 'youtube' }, 1)
+    })
+
+    it('clears a degraded extractor and updates the gauge', () => {
+        setExtractorDegraded('youtube', true)
+        setExtractorDegraded('youtube', false)
+
+        expect(isExtractorDegraded('youtube')).toBe(false)
+        expect(gaugeSetMock).toHaveBeenLastCalledWith(
+            { extractor: 'youtube' },
+            0,
+        )
+    })
+
+    it('tracks extractors independently', () => {
+        setExtractorDegraded('youtube', true)
+
+        expect(isExtractorDegraded('youtube')).toBe(true)
+        expect(isExtractorDegraded('spotify')).toBe(false)
+    })
+})

packages/bot/src/handlers/player/extractorHealth.ts

@@ -0,0 +1,24 @@
+import { musicExtractorDegradedGauge } from '../../utils/monitoring/prometheus'
+
+const degradedExtractors = new Set<string>()
+
+/**
+ * Single source of truth for extractor health: updates both the in-process
+ * readable state (checked at /play error time, #1929) and the Prometheus
+ * gauge (scraped for alerting) together, so they can't drift apart.
+ */
+export function setExtractorDegraded(
+    extractor: string,
+    degraded: boolean,
+): void {
+    if (degraded) {
+        degradedExtractors.add(extractor)
+    } else {
+        degradedExtractors.delete(extractor)
+    }
+    musicExtractorDegradedGauge.set({ extractor }, degraded ? 1 : 0)
+}
+
+export function isExtractorDegraded(extractor: string): boolean {
+    return degradedExtractors.has(extractor)
+}

packages/bot/src/handlers/player/playerFactory.ts

@@ -12,6 +12,7 @@ import type { CustomClient } from '../../types'
 import { errorLog, infoLog, warnLog } from '@lucky/shared/utils'
 import { createResilientStream } from './streamBridge'
 import { withTimeout } from './withTimeout'
+import { setExtractorDegraded } from './extractorHealth'
 
 type CreatePlayerParams = {
     client: CustomClient
@@ -154,6 +155,7 @@ const loadYoutubeExtractor = async (player: Player): Promise<void> => {
             const YoutubeExtractor =
                 mod.YoutubeExtractor ?? mod.YoutubeiExtractor
             if (!YoutubeExtractor) {
+                setExtractorDegraded('youtube', true)
                 warnLog({
                     message:
                         'discord-player-youtubei: no extractor export found — skipping YouTube extractor',
@@ -167,6 +169,7 @@ const loadYoutubeExtractor = async (player: Player): Promise<void> => {
             )
 
             if (registered) {
+                setExtractorDegraded('youtube', false)
                 infoLog({
                     message:
                         'Registered YoutubeExtractor (SoundCloud bridge + YouTube fallback)',
@@ -191,6 +194,7 @@ const loadYoutubeExtractor = async (player: Player): Promise<void> => {
 
     // Escalate to errorLog (not warn): the bot is now running degraded and
     // YouTube playback will fail until restart — this must be visible.
+    setExtractorDegraded('youtube', true)
     errorLog({
         message:
             'YouTube extractor unavailable after retries — #play of YouTube URLs will fail until restart. Falling back to SoundCloud/Spotify only.',

packages/bot/src/utils/monitoring/prometheus.ts

@@ -103,6 +103,21 @@ export const guildLeavesTotal = new Counter({
     registers: [registry],
 })
 
+/**
+ * Gauge: whether a music extractor is currently known-degraded (1) or
+ * healthy (0), labelled by extractor name. Pushed directly by
+ * `extractorHealth.ts` on registration success/failure — not lazily
+ * collected, since registration is an event, not a queryable state.
+ * Distinct from `lucky_bot_gateway_connected`: the gateway can be fully
+ * connected while a specific extractor is unusable (#1929).
+ */
+export const musicExtractorDegradedGauge = new Gauge<'extractor'>({
+    name: 'lucky_music_extractor_degraded',
+    help: 'Whether a music extractor is currently known-degraded (1) or healthy (0), labelled by extractor name.',
+    labelNames: ['extractor'],
+    registers: [registry],
+})
+
 /**
  * Render the registry as Prometheus text exposition format.
  */