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.

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:

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 and 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.

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
• Getting Started With Web Studio
• Setting Up Preview
• Web Studio SDK on GitHub
• Email support@agilitycms.com with your instance GUID, the deployment URL, and the console messages from the framed page.