Troubleshooting

If Autorender Native isn’t behaving as expected, turn on debug logging first. It names most problems directly in the browser console, so you rarely have to guess.

Turn on debug logging first

Add debug=1 to the script URL and reload with the console open.

<script defer
  src="https://cdn.autorender.io/native/v1/native.min.js?ws=LOKVTtKVGb&debug=1"
></script>

Production is silent except for one always-on fatal error when ws is missing. With debug=1 the runtime logs the specific reason it skipped, resized, or downgraded an element — each message names the element it applies to. Turn it off again before you ship.

Common problems

What you see	What it means	Fix
No images load; console shows `Missing or invalid "ws"`	The workspace ID is missing or malformed, so the runtime disabled itself	Add `?ws=<workspace-id>` to the script URL; it must match `[A-Za-z0-9_-]{1,64}`
No images load; no console error	The script never loaded, or a Content Security Policy blocked a host	Confirm the `<script>` URL returns 200 and uses `defer`; if you send a CSP, allowlist `script-src https://cdn.autorender.io` and `img-src https://assets.autorender.io`
One image stays blank and gains the `ar-error` class	That variant failed to load — a wrong path, or a remote URL that isn’t reachable	Verify the source path exists in the workspace; for a remote `https://` URL, it must be public and return image content
An image loads, then a larger one refetches	Expected: the box grew past a `step` boundary and fired `ar:upgrade`	Nothing to fix; raise `step` to trade sharpness for fewer refetches
Layout jumps as images load; console shows `image has no width/height attributes or CSS aspect-ratio`	The box measured near-zero before the image loaded	Set both `width` and `height`, or a CSS `aspect-ratio`, so the browser reserves space
The same image is fetched twice per visit	`data-ar-src` and a real `src` are on the same non-hero `<img>`	Remove the real `src`; put the fallback in `<noscript>` instead
An image is blurry or smaller than expected	The rendered box is smaller than you think, an intrinsic cap engaged, or `max-dpr` clamped the density	Check the element’s real box; set `data-ar-intrinsic` to the true source size; raise `max-dpr` only for detail-critical imagery
`anticipation` seems ignored	An unencoded `%` in the script URL was dropped by the browser	Percent-encode it: `anticipation=20%25`
Images inserted by JavaScript aren’t optimized	They were added outside the live document, or the browser lacks `MutationObserver`	Insert nodes into the live page; Autorender picks up childList additions automatically
An image ignores the optimized `src` and loads its own source	The `<img>` still has a `srcset`, which the browser honors over the `src` the runtime sets	Remove `srcset` from marked images; mark a plain `<img>`, not a `<picture>`
Images inside a web component aren’t optimized	The runtime observes the light DOM only — shadow roots are not traversed	Render marked `<img>` and background elements in the light DOM

An image reports zero size

If an element measures zero width under its normal layout — often inside a container the runtime can’t measure directly — the console shows:

visible element has zero size — switching to compatibility measurement

The runtime recovers on its own after 3 consecutive zero-size measurements, switching to the compatibility path that derives width from an ancestor. To force that path from the first load, set data-ar-measure="compat" on the element. In compat mode the runtime sizes on width alone.

Compat is not a recovery for an element carrying a W/H size alias. Compat reports a height of 0, so an alias that needs a height waits forever — the element stays in a waiting state and never loads, and it fires no ar:error. The switching to compatibility measurement line in the debug log is the only signal. Give alias elements a reliable box, or use explicit token values instead of aliases.

A hero image is still slow (LCP)

data-ar-eager skips lazy loading, but it does not fix LCP. The browser’s preload scanner can’t see a data-ar-src at parse time, so with debug=1 you’ll see:

Eager image has no parse-time src and may delay LCP.

For the single largest hero image, add a <link rel="preload"> to a hand-built delivery URL so the browser starts the fetch during HTML parsing — a real src would be fetched in full and then replaced. See the hero pattern.

Still stuck?

If you’ve worked through the checks above and images still don’t load as expected, contact Autorender support. Include your workspace ID, the full script URL (with debug=1), a sample element’s HTML, and the exact console output.

Next steps

Configuration

The script-URL parameters behind most of these messages.

Attributes

Every data-ar-* attribute, including intrinsic and measure.

Events and classes

The ar-error class and ar:error event these checks refer to.

Introduction

The correct baseline setup to compare against.

Get started

Storage

Native (HTML)

Transformations

Optimization

Video

Build with AI

Resources

Turn on debug logging first

Common problems

An image reports zero size

A hero image is still slow (LCP)

Still stuck?

Next steps

Configuration

Attributes

Events and classes

Introduction

​Turn on debug logging first

​Common problems

​An image reports zero size

​A hero image is still slow (LCP)

​Still stuck?

​Next steps

Configuration

Attributes

Events and classes

Introduction

Turn on debug logging first

Common problems

An image reports zero size

A hero image is still slow (LCP)

Still stuck?

Next steps