diff --git a/src/platform/telemetry/imageFailureDiagnostics.test.ts b/src/platform/telemetry/imageFailureDiagnostics.test.ts
new file mode 100644
index 00000000000..1582da92e7f
--- /dev/null
+++ b/src/platform/telemetry/imageFailureDiagnostics.test.ts
@@ -0,0 +1,211 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import {
+ describeImageLoadFailure,
+ resetImageFailureProbesForTest
+} from '@/platform/telemetry/imageFailureDiagnostics'
+
+const ORIGIN = 'https://cloud.comfy.org'
+
+function respondWith(status: number) {
+ return vi.fn().mockResolvedValue({ status, type: 'basic', body: null })
+}
+
+describe('describeImageLoadFailure', () => {
+ beforeEach(() => {
+ resetImageFailureProbesForTest()
+ vi.stubGlobal('location', new URL(`${ORIGIN}/`))
+ })
+
+ it('reports the status the img error event withheld', async () => {
+ vi.stubGlobal('fetch', respondWith(401))
+
+ const result = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=a.png&type=output`
+ )
+
+ expect(result.status).toBe(401)
+ expect(result.probe_outcome).toBe('probed')
+ })
+
+ it('separates a missing output from a missing template', async () => {
+ vi.stubGlobal('fetch', respondWith(404))
+
+ const output = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?type=output&filename=${'a'.repeat(64)}.png`
+ )
+ const template = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=template-Magazine_Cover.png`
+ )
+
+ expect(output).toMatchObject({
+ status: 404,
+ resource_kind: 'output',
+ filename_kind: 'content_hash'
+ })
+ expect(template).toMatchObject({
+ status: 404,
+ resource_kind: 'unspecified',
+ filename_kind: 'template'
+ })
+ })
+
+ it('probes with credentials, or it would manufacture the 401 it measures', async () => {
+ const fetchSpy = respondWith(200)
+ vi.stubGlobal('fetch', fetchSpy)
+
+ await describeImageLoadFailure(`${ORIGIN}/api/view?filename=a.png`)
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({
+ credentials: 'include',
+ headers: { Range: 'bytes=0-0' }
+ })
+ )
+ })
+
+ it('records a network failure as an outcome rather than throwing', async () => {
+ vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new TypeError('offline')))
+
+ const result = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=a.png`
+ )
+
+ expect(result.probe_outcome).toBe('probe_failed')
+ expect(result.status).toBeUndefined()
+ })
+
+ it('caps probes so a node retrying one missing file cannot amplify', async () => {
+ const fetchSpy = respondWith(404)
+ vi.stubGlobal('fetch', fetchSpy)
+
+ const results = []
+ for (let i = 0; i < 25; i++) {
+ results.push(
+ await describeImageLoadFailure(`${ORIGIN}/api/view?filename=a.png`)
+ )
+ }
+
+ expect(fetchSpy).toHaveBeenCalledTimes(20)
+ expect(results.at(-1)?.probe_outcome).toBe('probe_capped')
+ // The report still lands — a capped probe must not silence the event.
+ expect(results.at(-1)?.source).toBe('node_image_preview')
+ })
+
+ it('does not probe cross-origin urls, which would report our own opacity', async () => {
+ const fetchSpy = respondWith(200)
+ vi.stubGlobal('fetch', fetchSpy)
+
+ const result = await describeImageLoadFailure(
+ 'https://cdn.example.com/a.png'
+ )
+
+ expect(fetchSpy).not.toHaveBeenCalled()
+ expect(result.same_origin).toBe(false)
+ expect(result.probe_outcome).toBe('probe_blocked')
+ })
+
+ it('reports an unparseable src instead of fabricating url shape fields', async () => {
+ const fetchSpy = respondWith(200)
+ vi.stubGlobal('fetch', fetchSpy)
+
+ const result = await describeImageLoadFailure('')
+
+ expect(fetchSpy).not.toHaveBeenCalled()
+ expect(result.probe_outcome).toBe('invalid_src')
+ })
+
+ it('reports a redirect as a redirect, not as our own status', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi
+ .fn()
+ .mockResolvedValue({ status: 0, type: 'opaqueredirect', body: null })
+ )
+
+ const result = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=a.png`
+ )
+
+ expect(result.probe_outcome).toBe('probe_redirected')
+ expect(result.status).toBeUndefined()
+ })
+
+ it('does not follow redirects — a signed storage URL answers on its own terms', async () => {
+ const fetchSpy = respondWith(200)
+ vi.stubGlobal('fetch', fetchSpy)
+
+ await describeImageLoadFailure(`${ORIGIN}/api/view?filename=a.png`)
+
+ expect(fetchSpy).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({ redirect: 'manual' })
+ )
+ })
+
+ it('survives a body cancel that rejects, rather than raising an unhandled rejection', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue({
+ status: 404,
+ type: 'basic',
+ body: { cancel: () => Promise.reject(new TypeError('already errored')) }
+ })
+ )
+
+ const result = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=a.png`
+ )
+
+ expect(result).toMatchObject({ status: 404, probe_outcome: 'probed' })
+ })
+
+ it('emits the report rather than holding it for a probe while the page unloads', async () => {
+ // A probe that never settles: without the unload race this await hangs and
+ // the failure is never reported.
+ vi.stubGlobal('fetch', vi.fn().mockReturnValue(new Promise(() => {})))
+
+ const pending = describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=a.png`
+ )
+ window.dispatchEvent(new Event('pagehide'))
+
+ await expect(pending).resolves.toMatchObject({
+ source: 'node_image_preview',
+ probe_outcome: 'probe_abandoned'
+ })
+ })
+
+ it('drops the unload listener once the race settles, on every failure', async () => {
+ vi.stubGlobal('fetch', respondWith(404))
+ // Observes registration without replacing it, so the listeners under test
+ // are the real ones the DOM holds — a mocked implementation would register
+ // nothing and the teardown assertion below would pass vacuously.
+ const addSpy = vi.spyOn(window, 'addEventListener')
+
+ for (let i = 0; i < 3; i++) {
+ await describeImageLoadFailure(`${ORIGIN}/api/view?filename=a${i}.png`)
+ }
+
+ const signals = addSpy.mock.calls
+ .filter(([type]) => type === 'pagehide')
+ .map(([, , options]) => (options as AddEventListenerOptions).signal)
+ addSpy.mockRestore()
+
+ expect(signals).toHaveLength(3)
+ // Every listener is torn down, so repeated failures cannot accumulate them.
+ expect(signals.every((signal) => signal?.aborted)).toBe(true)
+ })
+
+ it('carries page age, the field that distinguishes auth expiry from a 404', async () => {
+ vi.stubGlobal('fetch', respondWith(401))
+ vi.spyOn(performance, 'now').mockReturnValue(7_500_000)
+
+ const result = await describeImageLoadFailure(
+ `${ORIGIN}/api/view?filename=a.png`
+ )
+
+ expect(result.page_age_ms).toBe(7_500_000)
+ })
+})
diff --git a/src/platform/telemetry/imageFailureDiagnostics.ts b/src/platform/telemetry/imageFailureDiagnostics.ts
new file mode 100644
index 00000000000..bd000a93d92
--- /dev/null
+++ b/src/platform/telemetry/imageFailureDiagnostics.ts
@@ -0,0 +1,193 @@
+import type { ImageLoadFailureMetadata } from '@/platform/telemetry/types'
+
+/**
+ * An `
` `error` event carries no status, no headers and no body — the
+ * browser tells you it failed and nothing else. That is why FE-1595 needed the
+ * reporting artist's Network tab: `app:image_load_failed` fired on every broken
+ * preview but could not say whether the cause was an expired session cookie
+ * (401), a missing output (404), or a dropped connection.
+ *
+ * So we re-request the same URL once, only after a failure, and report the
+ * status the browser would not give us. The probe is deliberately cheap and
+ * deliberately incapable of making things worse:
+ *
+ * - `Range: bytes=0-0` asks for a single byte, so a probe of a 20MB output does
+ * not re-download it. Servers that ignore `Range` answer 200 with the body,
+ * which is why the response is never read.
+ * - `credentials: 'include'` mirrors how the browser sent the original `
`
+ * request. Probing without it would send no cookie and manufacture the very
+ * 401 we are trying to measure.
+ * - Failures resolve to `probe_failed`/`probe_blocked` rather than throwing. A
+ * diagnostic must never become the second error in the report.
+ */
+
+/** Probes are capped per page so a node retrying a missing file in a loop cannot amplify. */
+const MAX_PROBES_PER_PAGE = 20
+
+/**
+ * A probe that outlives this is worth less than the request it occupies. Kept
+ * short because the report is emitted after it: a long budget turns every
+ * failed image into a window where a page unload loses the event entirely.
+ */
+const PROBE_TIMEOUT_MS = 2_000
+
+let probesIssued = 0
+
+/** Test seam — the cap is module state that would otherwise leak across cases. */
+export function resetImageFailureProbesForTest(): void {
+ probesIssued = 0
+}
+
+/**
+ * `type` in an `/api/view` URL distinguishes a generated output from a user
+ * upload. A 404 on `output` means the result expired or was swept; a 404 on
+ * `input` means the upload never landed. They are different bugs and the
+ * current event cannot tell them apart.
+ */
+function resourceKind(url: URL): ImageLoadFailureMetadata['resource_kind'] {
+ const type = url.searchParams.get('type')
+ if (type === 'output' || type === 'input' || type === 'temp') return type
+ return url.searchParams.has('filename') ? 'unspecified' : 'not_api_view'
+}
+
+/**
+ * The filename shape separates "a generation we produced" from "a template
+ * asset we ship". Template thumbnails 404ing is a packaging bug on our side;
+ * a hashed output 404ing is a retention/lifecycle bug. Reporting the shape
+ * rather than the name keeps user-authored filenames out of telemetry.
+ */
+function filenameKind(url: URL): ImageLoadFailureMetadata['filename_kind'] {
+ const filename = url.searchParams.get('filename')
+ if (!filename) return 'none'
+ if (filename.startsWith('template-')) return 'template'
+ if (/^[0-9a-f]{64}\./i.test(filename)) return 'content_hash'
+ return 'named'
+}
+
+/**
+ * Resolves if the page starts going away, so a pending probe cannot hold the
+ * report hostage. Never resolves otherwise — it only ever loses the race.
+ *
+ * The caller aborts `signal` once the race settles. Without that the listener
+ * outlives every probe that wins, and this runs on *every* failed image —
+ * including those past the probe cap, where a node retrying a missing file can
+ * produce hundreds in one session.
+ */
+function abandonOnUnload(
+ signal: AbortSignal
+): Promise> {
+ return new Promise((resolve) => {
+ window.addEventListener(
+ 'pagehide',
+ () => resolve({ probe_outcome: 'probe_abandoned' }),
+ { once: true, signal }
+ )
+ })
+}
+
+async function probeStatus(
+ src: string
+): Promise> {
+ if (probesIssued >= MAX_PROBES_PER_PAGE) {
+ return { probe_outcome: 'probe_capped' }
+ }
+ probesIssued += 1
+
+ try {
+ const response = await fetch(src, {
+ method: 'GET',
+ credentials: 'include',
+ headers: { Range: 'bytes=0-0' },
+ // Our own status is the finding. Following a redirect would report the
+ // status of wherever `/api/view` sent us — a signed storage URL answering
+ // 200 or 403 on its own terms — and attribute it to our endpoint.
+ redirect: 'manual',
+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+ })
+ // A manual-redirect response is opaque: status reads 0 and no header is
+ // legible. That the endpoint redirected is still the answer, so it gets its
+ // own outcome rather than being reported as a status of 0.
+ if (response.type === 'opaqueredirect') {
+ return { probe_outcome: 'probe_redirected' }
+ }
+ // The body is never read: `Range` already bounded it, and cancelling here
+ // releases the connection instead of buffering an image we will not show.
+ // A cancel on an already-errored body rejects, and an unhandled rejection
+ // becomes a spurious Sentry report — so it is swallowed explicitly.
+ void response.body?.cancel().catch(() => {})
+ return { status: response.status, probe_outcome: 'probed' }
+ } catch (error) {
+ // An opaque/CORS/offline failure is itself the finding: the request never
+ // reached a server that could answer, so no status exists to report.
+ return {
+ probe_outcome:
+ error instanceof DOMException && error.name === 'TimeoutError'
+ ? 'probe_timeout'
+ : 'probe_failed'
+ }
+ }
+}
+
+/**
+ * Builds the metadata for one failed preview. Never throws and never rejects.
+ *
+ * `page_age_ms` is the field that would have identified FE-1595 on its own: the
+ * session-cookie bug could only strike a page open longer than the cookie's
+ * 2-hour life, so an auth-caused failure population skews old while a 404
+ * population does not. It is page age, not session age — a reload mints a fresh
+ * cookie, which is exactly the boundary that matters.
+ */
+export async function describeImageLoadFailure(
+ src: string
+): Promise {
+ const base: ImageLoadFailureMetadata = {
+ source: 'node_image_preview',
+ page_age_ms: Math.round(performance.now()),
+ online: navigator.onLine,
+ resource_kind: 'not_api_view',
+ filename_kind: 'none',
+ probe_outcome: 'probe_blocked'
+ }
+
+ // An empty src is not a malformed URL — it resolves to the page itself, so
+ // probing it would re-request the HTML document and report a 200 for an image
+ // that never loaded. Reject it before parsing.
+ if (!src.trim()) return { ...base, probe_outcome: 'invalid_src' }
+
+ let url: URL
+ try {
+ url = new URL(src, window.location.href)
+ } catch {
+ // A malformed src never reached the network, so there is nothing to probe
+ // and the shape fields would be fabrications.
+ return { ...base, probe_outcome: 'invalid_src' }
+ }
+
+ const shape = {
+ ...base,
+ resource_kind: resourceKind(url),
+ filename_kind: filenameKind(url),
+ same_origin: url.origin === window.location.origin
+ }
+
+ // Cross-origin images are opaque to `fetch` without CORS, so a probe would
+ // report our own failure rather than the server's answer.
+ if (!shape.same_origin) return shape
+
+ // The report is emitted after the probe resolves, so a page unload mid-probe
+ // would drop the event — the diagnostic would cost us the very failure it
+ // describes. Losing the status is survivable; losing the report is not.
+ const settled = new AbortController()
+ try {
+ return {
+ ...shape,
+ ...(await Promise.race([
+ probeStatus(src),
+ abandonOnUnload(settled.signal)
+ ]))
+ }
+ } finally {
+ // Drops the pagehide listener whichever side won.
+ settled.abort()
+ }
+}
diff --git a/src/platform/telemetry/types.ts b/src/platform/telemetry/types.ts
index a7933c157f7..40c2824b595 100644
--- a/src/platform/telemetry/types.ts
+++ b/src/platform/telemetry/types.ts
@@ -92,8 +92,35 @@ export interface UnifiedAuthRefreshMetadata {
retry_count?: number
}
+/**
+ * One failed image preview. An `
` error event reports no status, so
+ * everything past `source` is reconstructed by `describeImageLoadFailure()`:
+ * `status` comes from re-requesting the URL once, the rest from the URL and the
+ * page. Fields are optional because a probe that was capped, blocked or never
+ * applicable must still produce a report — a missing field is a real outcome,
+ * recorded in `probe_outcome` rather than guessed at.
+ */
export interface ImageLoadFailureMetadata {
source: 'node_image_preview'
+ /** HTTP status of the follow-up probe. Absent unless `probe_outcome` is `probed`. */
+ status?: number
+ probe_outcome?:
+ | 'probed'
+ | 'probe_failed'
+ | 'probe_timeout'
+ | 'probe_capped'
+ | 'probe_blocked'
+ | 'probe_redirected'
+ | 'probe_abandoned'
+ | 'invalid_src'
+ /** `/api/view?type=` — separates an expired output from a missing upload. */
+ resource_kind?: 'output' | 'input' | 'temp' | 'unspecified' | 'not_api_view'
+ /** Filename shape only; never the filename, which is user-authored. */
+ filename_kind?: 'content_hash' | 'template' | 'named' | 'none'
+ /** Time since this page loaded. Auth-expiry failures skew old; 404s do not. */
+ page_age_ms?: number
+ online?: boolean
+ same_origin?: boolean
}
/**
diff --git a/src/renderer/extensions/vueNodes/components/ImagePreview.test.ts b/src/renderer/extensions/vueNodes/components/ImagePreview.test.ts
index 969e25c0580..61ad824dbb1 100644
--- a/src/renderer/extensions/vueNodes/components/ImagePreview.test.ts
+++ b/src/renderer/extensions/vueNodes/components/ImagePreview.test.ts
@@ -166,11 +166,19 @@ describe('ImagePreview', () => {
expect(
screen.queryByRole('button', { name: 'Download image' })
).not.toBeInTheDocument()
- expect(
- useTelemetry()?.trackImageLoadFailed
- ).toHaveBeenCalledExactlyOnceWith({
- source: 'node_image_preview'
- })
+ // The report is emitted behind a diagnostic probe, so the error UI above
+ // asserts synchronously while the telemetry needs the probe to settle.
+ await vi.waitFor(() =>
+ expect(
+ useTelemetry()?.trackImageLoadFailed
+ ).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ source: 'node_image_preview',
+ probe_outcome: expect.any(String),
+ page_age_ms: expect.any(Number)
+ })
+ )
+ )
})
it('handles download button click', async () => {
diff --git a/src/renderer/extensions/vueNodes/components/ImagePreview.vue b/src/renderer/extensions/vueNodes/components/ImagePreview.vue
index 1ad4bbd9e81..6d62ea7c2ad 100644
--- a/src/renderer/extensions/vueNodes/components/ImagePreview.vue
+++ b/src/renderer/extensions/vueNodes/components/ImagePreview.vue
@@ -216,6 +216,7 @@ import Button from '@/components/ui/button/Button.vue'
import Skeleton from '@/components/ui/skeleton/Skeleton.vue'
import { useMaskEditor } from '@/composables/maskeditor/useMaskEditor'
import { useTelemetry } from '@/platform/telemetry'
+import { describeImageLoadFailure } from '@/platform/telemetry/imageFailureDiagnostics'
import { useToastStore } from '@/platform/updates/common/toastStore'
import { openHdrViewer } from '@/services/hdrViewerService'
import { useNodeOutputStore } from '@/stores/nodeOutputStore'
@@ -339,8 +340,14 @@ function handleImageError() {
stopDelayedLoader()
showLoader.value = false
imageError.value = true
- useTelemetry()?.trackImageLoadFailed({ source: 'node_image_preview' })
actualDimensions.value = null
+
+ // The error UI is already up; the diagnostic probe runs behind it so a slow
+ // or hanging re-request never delays what the user sees.
+ const failedUrl = currentImageUrl.value
+ void describeImageLoadFailure(failedUrl).then((metadata) => {
+ useTelemetry()?.trackImageLoadFailed(metadata)
+ })
}
function handleEditMask() {