> ## Documentation Index
> Fetch the complete documentation index at: https://autorender.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose Autorender Native when images don't load, resize, or size the way you expect — starting from the console.

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.

```html wrap theme={null}
<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`](/docs/native/configuration) 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`](/docs/native/attributes) to the true source size; raise [`max-dpr`](/docs/native/configuration) 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"`](/docs/native/attributes) on the element. In compat mode the runtime sizes on width alone.

<Warning>
  Compat is not a recovery for an element carrying a `W`/`H` [size alias](/docs/native/attributes#w-and-h-size-aliases). 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.
</Warning>

## 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](/docs/native/hero).

## 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

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" iconType="solid" href="/docs/native/configuration">
    The script-URL parameters behind most of these messages.
  </Card>

  <Card title="Attributes" icon="code" iconType="solid" href="/docs/native/attributes">
    Every `data-ar-*` attribute, including `intrinsic` and `measure`.
  </Card>

  <Card title="Events and classes" icon="bell" iconType="solid" href="/docs/native/events">
    The `ar-error` class and `ar:error` event these checks refer to.
  </Card>

  <Card title="Introduction" icon="bolt" iconType="solid" href="/docs/native/introduction">
    The correct baseline setup to compare against.
  </Card>
</CardGroup>