Skip to content

[backport core/1.49] fix: surface missing media on the promoted host widget - #14660

Merged
comfy-pr-bot merged 1 commit into
core/1.49from
backport-14578-to-core-1.49
Aug 4, 2026
Merged

comfy-pr-bot merged 1 commit into
core/1.49from
backport-14578-to-core-1.49

Conversation

@comfy-pr-bot

Copy link
Copy Markdown
Member

Backport of #14578 to core/1.49

Automatically created by backport workflow.

## Summary

Move missing-media error surfacing from the interior widget to the
promoted host widget, matching the ADR 0009 ownership model.

Built as a red-green pair. The tests were written and pushed first and
failed on CI; the implementation followed and turned them green, with
the failing and passing runs both linked below.

## Changes

- **What**:
- `refactor: extract the missing media pipeline seam` — moves
`runMissingMediaPipeline` / `cacheMediaCandidates` out of `ComfyApp`
into `src/platform/missingMedia/missingMediaPipeline.ts`, mirroring the
existing `missingModelPipeline.ts`. Pure move.
- Test commits — 30 failing unit tests across 6 files plus 3 E2E
scenarios, defining the contract below.
- `fix: surface missing media on the promoted host widget` — the
implementation.
- `refactor: derive missing media detection from the input spec` —
replaces the hardcoded `MEDIA_NODE_WIDGETS` map with the upload flags
the backend already declares.
- `fix: move the missing media error surface on promotion as well as
demotion` — closes the promotion half of the ownership transfer.
- `refactor: address review nits on the promoted missing media surface`.
- **Breaking**: none.
- **Dependencies**: none.

Production total: 332 insertions / 114 deletions across 9 files.

## Why

[#12197](#12197) (ADR
0009) made promoted widgets host-owned: the host `SubgraphNode` widget
owns the value and the interior widget only supplies schema/options
metadata.
[#13059](#13059)
updated **missing model** detection for that contract. **Missing media
was never updated** — `missingMediaScan.ts` still skips subgraph hosts
entirely and reads the interior widget.

What the user sees today, with a `LoadImage` inside a subgraph whose
`image` widget is promoted:

- The error is keyed to the interior node, so the errors-tab row
navigates to a node the user cannot edit — the interior widget is
disabled while promoted.
- Selecting a valid image on the host does not clear it. Entering the
subgraph re-creates the candidate from the stale interior value through
the `onNodeAdded` rescan.

## The contract these tests pin

A candidate is created from the **unlinked final editable value owner**.

| | `nodeId` | `widgetName` | `nodeType` |
| --- | --- | --- | --- |
| plain node widget | node execId | widget name | node type |
| promoted host widget | **host execId** | **host SubgraphInput name** |
**leaf node type** (e.g. `LoadImage`) |

1. A widget whose paired input slot has a link is not the value owner
and is skipped — promoted interior widgets and ordinary link-fed widgets
alike.
2. Media-widget identification reads the **leaf** widget's `InputSpec`
upload flags (`image_upload`, `animated_image_upload`, `video_upload`,
`audio_upload`) via `nodeDefStore.getInputSpecForWidget`. The tests were
written against the four-node `MEDIA_NODE_WIDGETS` map that existed at
the time; the later spec-based commit keeps every one of them green and
additionally covers custom loader nodes.
3. **Value and combo options are both read from the scanned widget** —
for a promoted widget that means the host, never the leaf.
4. Nested `A → B → C`: only `A` creates a candidate.
5. Two hosts sharing one subgraph definition produce independent
candidates.
6. **Liveness follows an any-consumer rule**: the candidate survives
while at least one fully-active path exists from the host input to a
concrete widget, and disappears when all of them are inactive or the
promotion is released.

## Review Focus

### Two intentional differences from missing model

**1. Options are read from the host, not the leaf.** `missingModelScan`
reads the interior widget's options. Media cannot: uploading through the
host dropdown appends the filename to the *host* widget's option list
only (`useWidgetSelectActions.handleFilesUpdate`), so reading leaf
options would report a just-uploaded file as missing on the next rescan.
Model combos have no upload control — `allowUpload` derives from the
same spec flags this PR now reads for detection — so the divergence does
not apply to them.

**2. Liveness is any-consumer, not first-link.** A `SubgraphInput` can
feed N interior widgets, and ADR 0009's primitive-fanout repair creates
exactly that shape. `resolveSubgraphInputLink` returns only the first
resolvable link as the "promoted representative", and
`missingModelScan.ts:219` uses that single representative for liveness.
In model today, with consumers A/B/C, bypassing **A alone** clears the
host error even though B and C still need the file — the outcome depends
on link order, which is an implementation detail. Media does not inherit
that. A follow-up PR will align `missingModelScan` to the same rule.

### What each wrong implementation trips on

| wrong implementation | caught by |
| --- | --- |
| reads the interior widget's value | `uses a valid host value even when
the linked interior value is stale` |
| reads the interior widget's options | `accepts a value found only in
the promoted host options` + `reports a value found only in the interior
leaf options as missing` |
| first-link representative for liveness | first-consumer scan case +
fanout lifecycle step 1 |
| last-link representative for liveness | last-nested-branch scan case +
fanout lifecycle step 2 |
| fixes the scan but not removal | the lifecycle reds |
| fixes removal but not the scan | the scan reds |

All four production liveness call sites are pinned separately — scan,
removal/mode-change, workflow-load async verification, realtime async
verification — so a partial implementation cannot go green.

### Test notes

- Some guards are green today by design. The `scanNodeMediaCandidates`
BYPASS/NEVER guards and three `missingMediaStore` tests pass without
production changes; they exclude specific wrong implementations rather
than proving the bug. Removal authority intentionally lives in the scan
rather than in a targeted store API.
- `MissingMediaCandidate` gains **no new field**. An earlier design
recorded the leaf execution path on the candidate; that cannot express
any-consumer liveness and goes stale when consumers change, so liveness
is re-derived from the host at check time.
- Commit 1 is a pure move. `this.rootGraph` was read lazily inside
`.then()` and is now captured as a parameter; these are equivalent
because `rootGraphInternal` has exactly one assignment site
(`app.ts:955`), so a single `LGraph` exists for the app's lifetime.
Verified by applying only the two production files to `main` and running
the full unit suite.

### Known unrelated CI noise

- `src/platform/cloud/onboarding/onboardingCloudRoutes.test.ts`
intermittently times out at 5s on module-level dynamic imports.
Reproduced on this branch's base commit.
- `.nvmrc` pins a floating `node 25`, resolved fresh per run, so
identical commits can behave differently across runs.

## Changes after the green run

Three commits landed after the red-green pair. All 51 checks pass on
`86382c61`.

**Spec-based media detection.** *Ecosystem impact: this broadens
detection from four hardcoded node types to every node whose combo input
declares an upload flag, so third-party media loaders will now surface
missing-media errors where they previously never did. `mesh_upload`
stays unhandled — missing media has no mesh surface yet.* Detection was
a hardcoded map of four node types (`LoadImage`, `LoadImageMask`,
`LoadVideo`, `LoadAudio`) keyed by widget name. It now reads the upload
flags the backend already declares on the combo `InputSpec`, resolved
through `nodeDefStore.getInputSpecForWidget` — the same API the Vue
layer uses to populate `SimplifiedWidget.spec`
(`useGraphNodeManager.ts:165`), and the same flag precedence
`WidgetSelect.vue` uses to decide whether a widget renders an upload
control. Custom loader nodes are now covered. `candidate.nodeType` still
comes from the leaf: the errors overlay formats it directly
(`missingErrorResolver.ts:265`), and a `SubgraphNode`'s own `type` is a
UUID, which `formatNodeTypeName` would pass through verbatim.

**Promotion, not just demotion.** Promotion transfers value ownership
from the interior widget to the host; demotion transfers it back. Only
demotion was handled, so promoting a widget with a missing file left the
error keyed to the interior node the user can no longer edit — the same
class of bug this PR exists to fix, reached by a different route — and
demoting deleted the error without re-checking the widget that regained
ownership. Both events now rescan the host subtree: whichever side lost
ownership fails the scope check and is dropped, whichever side gained it
is scanned fresh. Demotion keeps its explicit host removal because
`ensureWidgetRemoved` dispatches before the widget leaves the input, so
the scope filter cannot yet see it gone. Two tests, both
mutation-proven.

Two branches that could not change behaviour were removed: the
`app.rootGraph === graph.rootGraph` guard in `onNodeRemoved` (hooks
install on `canvasStore.currentGraph`, which may be a `Subgraph`, but
`Subgraph.rootGraph` returns the app's single root, so it is always
true), and the missing-widget early return in
`isMissingMediaCandidateScopeActive` (`getSlotFromWidget` accepts
`undefined`, so the branch returned exactly what the code below it
already returned).

## Follow-ups

An 18-lane blackbox review produced these. Each is real but outside this
PR's scope; none block it.

| # | item | why deferred |
| --- | --- | --- |
| 1 | `findNodesReferencingValues` skips subgraph hosts, so a deleted
asset stays written into the workflow JSON through a promoted host |
named as a non-goal below; extending it needs a decision on what
preview-clearing means for a host, whose outputs the interior node
produces |
| 2 | the promotion-listener `Map` keys on `Subgraph`, retaining
definitions until teardown | lifetime question that applies to the
sibling model path too |
| 3 | the per-node scan lost its node-type early bail, so a full-graph
scan is O(M·N) | needs a cheap pre-filter that does not reintroduce the
hardcoded map |
| 4 | per-node media verification is uncancellable; its `rootGraph`
staleness guard cannot fire for same-workflow edits | needs an
`AbortSignal` through the scan path, which `verifyMediaCandidates`
already accepts |
| 5 | `isWidgetMissingMedia` is a linear scan where the model store
precomputes a key `Set` | render-path optimisation, measurable only on
large graphs |
| 6 | `hasActiveConsumer` re-implements `resolveSubgraphInputLink`'s
traversal and sits in `resolveConcretePromotedWidget.ts` | unifying them
means changing the model path's first-link semantics, which item 8
covers |
| 7 | promoted-host uploads set no in-flight flag: the interior widget
is disabled so `useNodeImageUpload` never runs, and
`WidgetSelectDropdown` tracks upload state in a local `ref` | the
`isUploading` guard is therefore unreachable for promoted widgets;
fixing it is an upload-path change, not a detection change |
| 8 | an active *non-media* consumer keeps a missing-media error alive
that the user cannot clear | needs a product decision on what liveness
should mean for heterogeneous fanout |
| 9 | the scan reaches into the leaf for `candidate.nodeType`, which
only the overlay message consumes directly
(`missingErrorResolver.ts:265`); the row label already prefers the
node's display name | switching the overlay to the display name would
let the scan drop `resolvePromotedWidgetSource` entirely —
`getInputSpecForWidget` already walks the promoted chain itself, so
chain resolution would live behind one store API instead of being
re-derived here. Deferred because it changes a user-visible string
(i18n) and `nodeType` is a public field on `MissingMediaCandidate`
shared with grouping and the model-side symmetry |
| 10 | a media file drop calls `showPendingWarnings()` unconditionally
(`app.ts:714`), restoring `wf.pendingWarnings.missingMediaCandidates`
verbatim — so an error cleared by a bypass, a node deletion or a
demotion comes back, keyed to a node that may no longer exist |
**pre-existing, reproduces on `main`** — filed as
[FE-1487](https://linear.app/comfyorg/issue/FE-1487/cleared-missing-media-errors-reappear-after-a-media-file-drop-keyed-to).
Nothing outside the load pipeline updates that cache, and
`showPendingWarnings` re-writes what it read, so the divergence is
self-perpetuating. The restore path is shared with missing model and
missing node, so any fix has to be validated across all three |
| 11 | the upload-flag precedence in `mediaTypeFromSpec` duplicates
`WidgetSelect.vue:82-90`, which derives the same `AssetKind` from the
same flags and also handles `mesh_upload` | a shared
`assetKindFromComboSpec` would keep them from drifting when a flag is
added, but `WidgetSelect.vue` is outside this PR's diff |

## Non-goals

- Does not change missing **model** behavior.
- Does not change the hide-vs-disable UX for promoted widgets, which is
pending design.
- Does not widen `findNodesReferencingValues`; the deleted-asset path
will be fixed at its call site so the preview-clearing and
value-clearing consumers keep their current behavior.

## Red-green proof

| phase | commit | unit | e2e |
| --- | --- | --- | --- |
| Red |
[`e11161a8`](e11161a839)
|
[failed](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30760755440/job/91530691345)
|
[failed](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30760755459/job/91530918284)
|
| Green |
[`1fe2d9a8`](1fe2d9a85b)
|
[passed](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30765383959/job/91543058867)
|
[passed](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30765383923/job/91543279012)
|

At red, the only failing jobs were the unit suite, one chromium E2E
shard, and the `e2e-status` job that aggregates them; the other 47
checks passed. The failing unit files were exactly the six this PR
touches. The E2E failures were behavioural assertions rather than setup
errors — the first one printed the bug directly, with the errors-tab row
naming the interior node the user cannot edit:

```
Locator: getByTestId('missing-media-row')
Expected substring: "Subgraph with Promoted Missing Media - outer_image"
Received string:    "Load Image - image"
```

At green, all 50 checks pass, including the same three jobs. The three
commits added after that run are described above; the branch head
[`86382c61`](86382c6198)
is green on every check —
[unit](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30778317952/job/91578007298),
[e2e](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/30778317997/job/91579591949)
(27/27 jobs, covering the `cloud`, `mobile-chrome`, `mobile-safari`,
`chromium-2x` and `chromium-0.5x` projects as well as the 16 chromium
shards).

### Tests changed between the two runs

Two tests were corrected after the red run was recorded. Both are listed
here rather than folded in silently:

1. **`missingMediaStore.test.ts`** — the red-phase intersection type and
cast were removed and `isWidgetMissingMedia` is now called directly.
During red the store did not expose the method, so an optional member
kept the failure an `AssertionError` instead of a `TypeError`; once the
implementation landed the scaffolding became unnecessary. This completes
what was promised in the review thread.
2. **`useProcessedWidgets.test.ts`** — `otherWidget` was re-aimed from
`outer_image` to `outer_mask`. As written it shared its entire host
identity with `matchingWidget` and differed only in `sourceExecutionId`,
so it demanded source-path discrimination that this contract
deliberately removes — it could not pass under any implementation. It
remains a promoted widget, so the promoted path is still exercised, and
a mutation that drops the `widgetName` comparison in the store still
fails it.

No other test changed: the 193 `it`/`describe` titles across the six red
files are identical at both revisions, with no `skip` or `only` added,
and the fixtures, E2E specs and helpers are untouched.

### Verification beyond CI

- All ten contract rules were checked by mutation: 14 probes, 14 caught,
none survived. The commits added after the green run were
mutation-proven the same way — reverting the `widget-promoted` listener
fails the promotion test, reverting the demotion rescan fails the
demotion test, and reverting spec-based detection to the old map fails
the custom-node test.
- The E2E scenarios were run locally in both harnesses: the OSS chromium
project against this branch's Vite dev server on `:5173`, and the
`cloud` project against a `pnpm build:cloud` dist served by a local
backend, matching how CI builds and serves it.


## Video 


https://github.com/user-attachments/assets/2e88d76c-c54e-4b69-b4b7-8d97be29b1b4
@comfy-pr-bot comfy-pr-bot added the backport Backporting a PR onto a release candidate label Aug 4, 2026
@comfy-pr-bot
comfy-pr-bot enabled auto-merge (squash) August 4, 2026 04:30
@dosubot dosubot Bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label Aug 4, 2026
@dosubot

dosubot Bot commented Aug 4, 2026

Copy link
Copy Markdown

📄 Knowledge review

Dosu skipped reviewing this PR because your organization has used its 200 included credits for the month. Your usage will reset on 2026-09-01. To have Dosu review this PR before then, ask your organization admin to upgrade to a pro account.


Leave Feedback Ask Dosu about ComfyUI_frontend Add Dosu to your team

@github-actions

github-actions Bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

🎭 Playwright: ✅ 1789 passed, 0 failed

📊 Browser Reports
  • chromium: View Report (✅ 1768 / ❌ 0 / ⚠️ 0 / ⏭️ 5)
  • chromium-2x: View Report (✅ 2 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • chromium-0.5x: View Report (✅ 1 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • mobile-chrome: View Report (✅ 18 / ❌ 0 / ⚠️ 0 / ⏭️ 0)

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 08/04/2026, 04:32:36 AM UTC

Links

@comfy-pr-bot
comfy-pr-bot merged commit 9756f33 into core/1.49 Aug 4, 2026
75 checks passed
@comfy-pr-bot
comfy-pr-bot deleted the backport-14578-to-core-1.49 branch August 4, 2026 04:44
@codecov

codecov Bot commented Aug 4, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.27481% with 15 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/platform/missingMedia/missingMediaPipeline.ts 65.62% 11 Missing ⚠️
...latform/missingMedia/__fixtures__/promotedMedia.ts 97.26% 2 Missing ⚠️
src/platform/missingMedia/missingMediaScan.ts 96.77% 1 Missing ⚠️
src/scripts/app.ts 0.00% 1 Missing ⚠️
@@              Coverage Diff              @@
##           core/1.49   #14660      +/-   ##
=============================================
+ Coverage      78.47%   78.52%   +0.05%     
=============================================
  Files           1781     1784       +3     
  Lines         103859   104055     +196     
  Branches       31868    32769     +901     
=============================================
+ Hits           81502    81713     +211     
+ Misses         21926    21912      -14     
+ Partials         431      430       -1     
Flag Coverage Δ
unit 70.62% <94.27%> (+0.11%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/composables/graph/useErrorClearingHooks.ts 97.78% <100.00%> (+0.23%) ⬆️
...e/graph/subgraph/createPromotionErrorReconciler.ts 100.00% <100.00%> (ø)
...re/graph/subgraph/resolveConcretePromotedWidget.ts 98.68% <100.00%> (+0.90%) ⬆️
...orm/assets/utils/clearNodePreviewCacheForValues.ts 100.00% <ø> (ø)
...rm/assets/utils/markDeletedAssetsAsMissingMedia.ts 100.00% <100.00%> (ø)
src/platform/missingMedia/missingMediaStore.ts 97.22% <100.00%> (+1.83%) ⬆️
...nsions/vueNodes/composables/useProcessedWidgets.ts 94.88% <100.00%> (+0.05%) ⬆️
src/utils/graphTraversalUtil.ts 97.98% <ø> (ø)
src/platform/missingMedia/missingMediaScan.ts 98.71% <96.77%> (+0.23%) ⬆️
src/scripts/app.ts 58.44% <0.00%> (+0.43%) ⬆️
... and 2 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport Backporting a PR onto a release candidate size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants