# Troubleshooting Web Studio

> Source: https://agilitycms.com/docs/developers/troubleshooting-web-studio

Find your symptom below. Each section lists the likely causes in the order worth checking. For the full setup, see [Set Up Web Studio with Any Framework](/docs/developers/web-studio-setup-any-framework).

> [!TIP]
> Most Web Studio problems show up in the browser console of the framed page. Open your browser's developer tools, pick your site's frame in the console's context menu, and look for messages that start with `Web Studio SDK`.

## The site won't load in the frame

**Symptoms:** a blank frame, or a "refused to connect" or "refused to display" message where your site should be.

Your site's response headers forbid framing. Check what your deployment actually sends:

```bash
curl -sI https://your-preview-site.com/ | grep -i -E "x-frame-options|content-security-policy"
```

- **`X-Frame-Options: DENY` or `SAMEORIGIN`** blocks Web Studio. Remove it and send `Content-Security-Policy: frame-ancestors 'self' https://app.agilitycms.com;` instead.
- **A `frame-ancestors` directive that doesn't list `https://app.agilitycms.com`** blocks Web Studio. Add it.
- **Two policies.** If a header is set in more than one place (your app, your host, a CDN or proxy), the browser enforces all of them. Check each layer, and test the URL editors actually use, not just your origin server.
- **ASP.NET Core forms.** Antiforgery adds `X-Frame-Options: SAMEORIGIN` to responses that render antiforgery tokens. Set `SuppressXFrameOptionsHeader = true` in `AddAntiforgery` options.
- **Only some pages fail.** The header is probably applied per route. Make sure it covers every page, and every deployment editors open in Web Studio, production included.

Web Studio checks your Content Security Policy when it loads your site and explains what to change if the policy blocks it.

## The frame is blocked as mixed content

**Symptoms:** the frame stays empty and the console mentions mixed content, or an insecure frame.

Agility runs on HTTPS, so the browser blocks any `http://` page inside it.

- Register the deployment with an `https://` URL in **Settings > Sitemaps**.
- Check that your site doesn't redirect HTTPS requests to HTTP, for example on a trailing-slash or locale redirect.
- Load the SDK script over HTTPS.
- `http://localhost` is allowed, because browsers treat localhost as trusted. Other local hostnames, such as a custom `.test` domain over HTTP, are blocked.

## Web Studio shows published content instead of my changes

**Symptoms:** the frame loads, but it shows the live site. Saved changes don't appear.

The preview key isn't being applied. Work through the request from the outside in:

1. **Is the request reaching your code?** A CDN or edge cache can answer with cached, published HTML before your app sees `agilitypreviewkey`. On Next.js this affects prerendered pages on [Vercel](/docs/nextjs/deploying-next-js-to-vercel) and [Netlify](/docs/nextjs/deploying-next-js-to-netlify); both guides show the fix. Elsewhere, make sure requests that carry `agilitypreviewkey`, or your preview cookie, bypass the cache.
2. **Does the key validate?** The site must hash the same security key the instance uses. Check the value configured on the deployment you're previewing (`AGILITY_SECURITY_KEY` in the Next.js starter, `AppSettings:SecurityKey` in the .NET starter). If you compare keys yourself, replace spaces with `+` first, because `+` becomes a space when a query string is decoded.
3. **Does preview mode survive navigation?** The first request carries the key; later clicks inside the frame usually rely on a cookie. Inside Web Studio your site is a cross-site frame, so that cookie must be `SameSite=None; Secure`. Next.js draft mode already sets its cookie that way outside development. Some browsers, or browser settings, block cookies in cross-site frames entirely. If that's the cause, preview in a new tab instead.
4. **Is preview content being read?** In preview mode the site must call the API with the preview API key, which returns saved, unpublished content.
5. **Was the change saved?** Without live updates, the preview only shows what has been saved.

More detail for Next.js: [Preview URL Lifecycle](/docs/nextjs/preview-url-lifecycle).

## Agility says the SDK isn't installed

**Symptoms:** Web Studio shows a notice that the Web Studio SDK is not installed, or it doesn't follow you as you click between pages.

- **Is the script on the page?** View the source of the framed page. If you load the SDK only in preview mode, check that preview mode is actually on (see the previous section).
- **Did the script load?** Look in the Network tab for `index.js` from `unpkg.com`. A Content Security Policy `script-src` that doesn't allow `https://unpkg.com` blocks it, and so can a browser extension or network filter that blocks unpkg.
- **Is the page in a frame?** The SDK does nothing in a normal browser tab. Test inside Web Studio.

## No outlines, or clicking a field does nothing

**Symptoms:** the site loads with the SDK, but components aren't outlined and nothing opens for editing.

Check the console first. The SDK names the problem:

- **"no guid found on body element":** add `data-agility-guid="YOUR_INSTANCE_GUID"` to `<body>`. It must be on `<body>`, not `<html>`.
- **"no pageID found on the `data-agility-page` element":** add `data-agility-page` with the numeric page ID to the element that wraps the page.

Then check the markup:

- **The GUID is for the wrong instance.** The SDK ignores messages for any GUID but the one on `<body>`. A site reading content from one instance and showing another's GUID won't respond.
- **Components aren't tagged.** Each component's outermost element needs `data-agility-component` with that component's content ID, not the page ID.
- **Fields are outside their component.** A field belongs to the nearest tagged component or list item around it. A field rendered outside that element isn't editable.
- **Items from a linked list aren't tagged.** Each item needs `data-agility-nested-listitem` with its own content ID.

## A field doesn't update as I type

**Symptoms:** outlines and editing work, but the preview doesn't change until you save.

- **The field can't update live.** Web Studio marks fields that need a save before the change shows. That's expected.
- **The value is formatted in code.** Live updates write the raw field value. A date your code formats, or Markdown your code converts to HTML, shows unformatted while typing and correctly after saving.
- **HTML shows as text.** Add `data-agility-html="true"` to the field element so the value is inserted as HTML.
- **An image doesn't change.** The SDK updates the first `<img>` inside the element tagged with `data-agility-field` (and any `<source>` in a `<picture>`). Put the attribute on a wrapper around the image.
- **The field name doesn't match.** `data-agility-field` must be the field name from the model.

## My preview bar shows inside Web Studio

Add `data-agility-previewbar="true"` to your preview bar's outer element. The value `"true"` is required; the attribute on its own isn't enough.

## Still stuck?

- [Set Up Web Studio with Any Framework](/docs/developers/web-studio-setup-any-framework)
- [Getting Started With Web Studio](/docs/overview/web-studio)
- [Setting Up Preview](/docs/developers/setting-up-preview)
- [Web Studio SDK on GitHub](https://github.com/agility/web-studio-sdk)
- Email [support@agilitycms.com](mailto:support@agilitycms.com) with your instance GUID, the deployment URL, and the console messages from the framed page.