# 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`](../api/ProblemCode.md) · 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`](../api/SceneModelOptions.assetBaseUrl.md), by default the runtime's asset root; every other URL (a texture or environment in a rule, [`materials.create`](../api/Materials.create.md), [`apply`](../api/Writer.apply.md) 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)`](../api/Session.transaction.md) 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

- [`ActivateARReport.problems`](../api/ActivateARReport.problems.md): For the runtime's own USDZ or WebXR copy of the committed product: 'asset-failed' for each placed ModelNode or `kind: 'model'` collection item it left out because its asset is unloaded, as [`ExportResult.problems`](../api/ExportResult.problems.md).
- [`CaptureResult.problems`](../api/CaptureResult.problems.md): 'ready-timeout', or 'asset-failed' for a slot drawn with the stand-in of a detail map that failed).
- [`Collection.set`](../api/Collection.set.md): Asset failures are `problems` ('asset-failed', `path` the item's address, or the stage layer's for its `stage`, [`Problem.path`](../api/Problem.path.md)).
- [`ExportOptions.prepare`](../api/ExportOptions.prepare.md): `copy.load` resolves at the call with the item's part, which has no bounds on the copy: its GLB loads when the file is written, and one that fails is an 'asset-failed' in [`ExportResult.problems`](../api/ExportResult.problems.md).
- [`ExportResult.problems`](../api/ExportResult.problems.md): Non-fatal problems of this export: 'asset-failed' (`node`, `url`) for each ModelNode the committed model places (spec section 6.9, ID10) whose asset is unloaded when the export reads the committed state, so the file lacks it, unless `query` can't match that node's parts (it names only a `collection`, a `key`, a `role` other than 'product', or another `node`); and 'asset-failed' (`path` the…
- [`HoloAssetError.problem`](../api/HoloAssetError.problem.md): The same failure as data ('asset-failed'), safe to log or send.
- [`IModelNode.optGlbUrl`](../api/IModelNode.optGlbUrl.md): If it fails to fetch, decrypt or parse, after its own `.holo` → `plainOptGlbUrl` fallback, the runtime tries `glbUrl` once, with its `.holo` → `plainGlbUrl` fallback, and records 'asset-degraded' with `url` this URL; only when that fails too is the node unloaded, with 'asset-failed' naming the last URL tried.
- [`InfoReport.problems`](../api/InfoReport.problems.md): This session's recent Problems, oldest first: the last 50 of any code, plus the last 20 'asset-failed', 'sync-failed' and 'render-lost' entries even when older, so budget codes never push those out.
- [`Problem.asset`](../api/Problem.asset.md): For 'asset-failed' and 'asset-degraded': what failed.
- [`Session.export`](../api/Session.export.md): A placed ModelNode or `kind: 'model'` item whose asset is unloaded has no parts, so it is not in the file; `problems` names it ('asset-failed', [`ExportResult.problems`](../api/ExportResult.problems.md)).
- [`Session.undo`](../api/Session.undo.md): A reload that fails is not equal: the undo commits with the node back in the model, unloaded, and 'asset-failed' in `problems` (spec section 6.4).
- [`Stage.set`](../api/Stage.set.md): An environment or panorama that fails is a problem ('asset-failed', `path` `/look/collections/{name}/stage`, `asset` 'environment' or 'texture', [`Problem.path`](../api/Problem.path.md)): the rest of the settings commit, and the environment or panorama drawn before stays, as a failed texture keeps its slot's look (spec section 6.4).
- [`Writer.apply`](../api/Writer.apply.md): Asset failures are `problems` ('asset-failed'); a rule that matches nothing records 'target-unmatched'.
- [`Writer.applyPatch`](../api/Writer.applyPatch.md): Asset failures: `problems`, so throwing on 'asset-failed' rolls the transaction back.
- [`testing.FakeSession.script`](../api/testing.FakeSession.script.md): With `fail`, `problem` picks the spec's section 6.4 row: 'sync-failed' is the internal-failure row (a state write rolls back with reason 'internal-error'; a 'collection.load' resolves, then its commit drops the item), 'asset-failed' the asset rows (a declarative write commits without it, an imperative load rejects HoloAssetError): every asset that write fetches fails once, assets already loaded…
- [`testing.FakeSessionOptions.assets`](../api/testing.FakeSessionOptions.assets.md): An entry with `load.fail` fails as that URL's fetch or decode would, `load.ms` after its request (as a `models` entry's failure), once per request: each slot that names it records its own 'asset-failed' (`url` as written, `asset` 'texture' or 'environment', and `op`): a stored MaterialNode's map names that MaterialNode in `node`, a collection item's or a stage layer's carries its `path`, and a…
- [`testing.FakeSessionOptions.models`](../api/testing.FakeSessionOptions.models.md): An entry whose `load.fail` is set fails as that URL's fetch, decrypt or key would and the chain goes on: a later entry that loads records 'asset-degraded' (`url` the first URL that failed); none records 'asset-failed' (`url` the last URL tried).

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

## Recorded by

- the table row `failure-matrix/cases/texture-fails` (`tables/failure-matrix.json`)
- the table row `failure-matrix/cases/glb-fails` (`tables/failure-matrix.json`)
- the table row `failure-matrix/cases/holo-fails-plain-twin` (`tables/failure-matrix.json`)
- the table row `failure-matrix/cases/opt-glb-fails` (`tables/failure-matrix.json`)
- the table row `failure-matrix/cases/failure-window` (`tables/failure-matrix.json`)
- the table row `failure-matrix/cases/collection-load-fails-through-tx` (`tables/failure-matrix.json`)
- the table row `failure-matrix/errorCases/asset-failure` (`tables/failure-matrix.json`)
- the table row `hold/cases/case-2` (`tables/hold.json`)