Documentation

Troubleshooting

Every refusal is structured: a code, a reason, the path of the offending value and, usually, a hint with the allowed alternatives. Nothing is half-installed or approximated.

Exit codes

`0`	ok
`1`	rejected (structured errors in errors[]): integrity, security, conflict, invalid request
`2`	usage error
`3`	blocked: registry unreachable, credential missing, invalid or expired, prerequisite missing
`4`	not implemented (e.g. --export-glb)
`6`	internal error

Common errors

Code	Meaning	What to do
`REGISTRY_UNREACHABLE (exit 3)`	The CLI cannot reach the registry.	Check AGENT_READY_ASSETS_REGISTRY: the address of this website, scheme and host only (https://, or http:// only to loopback), and your network.
`ENTITLEMENT_REQUIRED / UNAUTHORIZED (exit 3)`	No token, a token that is not valid, or an account that does not own the package (for example the full kit in the quickstart).	Create an API token on your account page and export AGENT_READY_ASSETS_TOKEN. Without kit access, follow the free sampler path (/docs/sampler): its assets are public and need no token.
`DOWNLOAD_GRANT_EXPIRED / DOWNLOAD_GRANT_USED_UP (add … --url)`	A download link from the account page is short-lived and works a limited number of times (the account page shows both for each link).	Request new links on the account page and run the printed commands right away; set up the project (starter, SDK, pnpm install) first.
`MAGIC_LINK_EXPIRED / MAGIC_LINK_USED / MAGIC_LINK_INVALID`	A sign-in link works once and expires after a short time.	Request a new link on the account page; open the newest one.
`PRODUCT_NOT_RELEASED (checkout)`	The product has no released version, so it cannot be bought.	Nothing to fix on your side. Evaluate with the demos, the catalog, the quality reports and the free sampler.
`HOST_NOT_ALLOWED (HTTP 421)`	The request named another host than the site’s (for example an IP address instead of the host name).	Use the origin exactly as shown in your address bar.
`pnpm install fails on a file:vendor/… dependency`	The SDK tarballs are not in vendor/, or not the ones the lockfile pins.	Copy the SDK tarballs you were given into vendor/ (quickstart step 2) and run pnpm install --frozen-lockfile again.
`npx: 404 Not Found … registry.npmjs.org/agent-ready-assets`	npx ran outside a project with the SDK installed and looked the CLI up on the public npm registry, where we publish nothing.	Run the command inside your project (after pnpm install), or use pnpm exec agent-ready-assets …, which never downloads.
`(!) Some chunks are larger than 500 kB after minification (pnpm run build)`	A Vite warning about the size of the three.js bundle, not an error.	Nothing to do. A published build ships every installed file under public/assets; the licence (/license) says what a build may contain.
`ENTITLEMENT_EXPIRED (exit 3)`	The account’s access to the package has expired or was revoked.	Check your downloads on the account page.
`DEPENDENCY_MISMATCH (exit 1)`	The project’s @agent-ready-assets/runtime-three is older than the package needs (a package built with SDK 0.5.1 needs SDK 0.5.1).	Upgrade all SDK packages together (the hint names npm install @agent-ready-assets/runtime-three@0.5.1), then repeat the add / kit add. Nothing was written.
`FILE_CONFLICT / VERSION_CONFLICT (exit 1)`	An installed file was changed, or another version is installed.	Repeat the same add / kit add with --force to restore the published bytes.
`LOCKFILE_MISMATCH (verify)`	Files differ from assets.lock.json.	The message names each file; reinstall with --force.
`PACKAGE_HASH_MISMATCH / SIZE_MISMATCH / PIN_MISMATCH`	Downloaded bytes are not the pinned ones.	Nothing was written. Retry; never bypass the check.
`MISSING_DEPENDENCY`	A modular host’s pinned parts are not installed.	Use kit add, or add each part named in the hint.
`UNSUPPORTED_OPERATION / UNKNOWN_CAPABILITY`	The request is not a declared capability (e.g. storeys).	Run inspect --capabilities; report the limitation instead of approximating it.
`INVALID_PARAMETER (OUT_OF_RANGE, OFF_STEP, NOT_IN_CHOICES, WRONG_TYPE)`	A value outside the declared range, step or choices.	Use the values the error’s hint lists.
`INCOMPATIBLE_PART (PART_NOT_ALLOWED, PART_NOT_IN_KIT)`	A swap names a part outside the slot’s allowlist or the installed kit.	Use a choice id from the capability (not a part ref).
`PATH_OUTSIDE_PROJECT / OUTPUT_EXISTS (exit 1)`	customize writes only inside the project and never overwrites a file without --force.	Write under the project (e.g. src/generated/…) or pass --project. To only check a config, add --dry-run: it accepts any --output and names the problem in warnings.
`VERSION_MISMATCH`	A config or scene pins another asset version than the installed one.	Re-pin the config/scene to the installed version and validate again.
`SNAP_INCOMPATIBLE / SNAP_OCCUPIED / SNAP_CYCLE / INSTANCES_OVERLAP`	A scene 1.1.0 snap is not possible as written.	scene validate --resolve names the instance; the hint lists compatible connectors.
`RELEASED_SOURCE / INSTANCE_UNKNOWN (town.customize)`	The scene was released, or the id is not an instance of it.	Assemble the scene again; use an instance_id from the scene file (town.instances).
`Missing textures, “Refused to connect to blob:” (Content-Security-Policy)`	three.js reads the textures embedded in a GLB through blob: URLs, which a connect-src without blob: refuses.	Add blob: to connect-src (img-src needs blob: and data: too). The SDK itself needs no 'unsafe-eval': its schema validators are precompiled.
`VARIANT_NOT_AVAILABLE / DECODER_REQUIRED`	A load asked for an optimized GLB variant, or a GLB declares decoders.	Load the reference GLB (no variant option): no optimized GLB variant is published.
`verify-project BLOCKED (exit 3)`	No Chromium in the project.	pnpm exec playwright install chromium (the CLI only uses the project’s own Playwright).
`TLS_UNTRUSTED / UNSAFE_ORIGIN`	Certificate not trusted, or a plain http registry that is not loopback.	Use the https origin of the registry.

TypeScript cannot find the types

Since SDK 0.5.1 every package carries its declarations next to its JavaScript and names them in package.json; import by package name. npx agent-ready-assets doctor prints the path of the installed runtime packages.

Import	Declarations
`@agent-ready-assets/contracts`	`node_modules/@agent-ready-assets/contracts/dist/index.d.ts`
`@agent-ready-assets/contracts/consumer`	`node_modules/@agent-ready-assets/contracts/dist/consumer.d.ts`
`@agent-ready-assets/contracts/canonical`	`node_modules/@agent-ready-assets/contracts/dist/canonical.d.ts`
`@agent-ready-assets/contracts/hash`	`node_modules/@agent-ready-assets/contracts/dist/hash.d.ts`
`@agent-ready-assets/customization`	`node_modules/@agent-ready-assets/customization/dist/index.d.ts`
`@agent-ready-assets/runtime-three`	`node_modules/@agent-ready-assets/runtime-three/dist/index.d.ts`
`@agent-ready-assets/runtime-r3f`	`node_modules/@agent-ready-assets/runtime-r3f/dist/index.d.ts`
`@agent-ready-assets/asset-cli`	`node_modules/@agent-ready-assets/asset-cli/dist/index.d.ts`

A deep import of the old 0.4.0 location (dist/types/packages/…) no longer resolves; switch it to the package name.

The receipt is optional and best effort: the label and the exit code never depend on it. A warning names why nothing was recorded:

`NOT_VERIFIED`	The run was not labelled LOCALLY_VALIDATED or STATICALLY_VALID, so nothing was sent.
`DO_NOT_TRACK`	DO_NOT_TRACK=1 is set: nothing was sent.
`NO_REGISTRY`	No registry origin (--registry, AGENT_READY_ASSETS_REGISTRY or assets.lock.json).
`UNSAFE_ORIGIN`	The origin is plain http and not loopback.
`REGISTRY_CONFLICT`	The origin differs from the one assets.lock.json pins.
`REGISTRY_UNREACHABLE`	The receipt could not be delivered (best effort; the run itself is unaffected).
`HTTP_<status>`	The registry answered with that HTTP status.

A large scene makes many draw calls

Assemble it with { optimize: true } or wrap the <Asset>s in <OptimizedScene> and compare town.optimization.stats() (drawsBefore, drawsAfter). Recoloured materials and running clips are not batched by design. See performance.

Demos do not start

The demos need WebGL. If a demo shows a render with a note instead, WebGL is turned off or unavailable (for example, hardware acceleration disabled); the rest of the site works without it.

Still stuck?

Add --json to any CLI command for the full structured output: errors[].code, reason, hint and, for refused customizations, the allowed alternatives. Look the code up above and on capabilities and limits. Support says how to reach us.