Problem code 'asset-failed' ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts, tables/problems.json and services/onsite-scripter/scripts/contract-docs-what-to-do.json by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

A member of ProblemCode · stable · since 2.0.0

A GLB, texture or HDR failed in a declarative write; the write committed without it.

What to do ​

The write committed without the asset: fix problem.url (as written, before resolution: does it load in a browser, does CORS allow it), then write it again; the same URL is not fetched again inside its failure window. Where a relative URL resolves depends on what named it. A URL of the scene model (problem.node is set: a node's GLB, a stored MaterialNode's map) resolves beneath SceneModelOptions.assetBaseUrl, by default the runtime's asset root; every other URL (a texture or environment in a rule, materials.create, apply or a stage layer, a collection item's) resolves against the page's document.baseURI, never assetBaseUrl, so pass those absolute (new URL(path, assetBaseUrl).href): on a Shopify app-proxy page the page is the shop, not your app. A collection item's or stage layer's failure carries its path. A rule's texture carries no node or path: match it to its write by problem.op. Every write lists one 'asset-failed' for each node it places that is still without its asset, a node an earlier write failed included, so to make what a write adds all or nothing, run it in session.transaction(work) and throw when its Report lists an 'asset-failed' for a node the model before it (tx.getSceneModel()) didn't hold, which rolls the transaction back; throwing on any 'asset-failed' would roll back every later write once one stored node's asset stays broken.

ts
await session.transaction(async (tx) => {
  const had = nodeIdsOf(tx.getSceneModel());
  const s = await tx.setSceneModel(model);
  // A node the model already held lists its own failure too: act on the added ones.
  if (s.problems.some((p) => p.code === 'asset-failed' && p.node && !had.has(p.node))) {
    throw new Error('asset failed'); // rolls the transaction back
  }
});

Where the declaration names it ​

The set is open: handle a code you don't know ('other').

Recorded by ​