windmill-labs/windmill · error

App preview is not ready

Error message

App preview is not ready

What it means

captureScreenshot in RawAppEditor.svelte grabs the app preview via the preview iframe's contentDocument.body. It throws 'App preview is not ready' when the iframe reference is missing, the iframe has not reported load completion (previewIframeLoaded false), or the document body is unavailable — i.e. a screenshot was requested before the preview finished rendering.

Source

Thrown at frontend/src/lib/components/raw_apps/RawAppEditor.svelte:1873

			el.style.setProperty('white-space', replacement, 'important')
			return () => {
				if (prev) el.style.setProperty('white-space', prev, prio)
				else el.style.removeProperty('white-space')
			}
		})
		return () => restores.forEach((r) => r())
	}

	// Capture the live preview as a PNG data URL. The preview iframe
	// (/ui_builder/app-preview.html) is same-origin with no sandbox, so its rendered
	// document is reachable and can be serialized from here. There is no native
	// element-screenshot API; modern-screenshot reconstructs the DOM into an SVG
	// foreignObject, so a WebGL canvas is only captured when its context was created
	// with preserveDrawingBuffer. Lazy-imported so the library only loads on demand.
	const captureScreenshot: RawAppScreenshotRequester = async () => {
		const target = previewIframe?.contentDocument?.body
		if (!previewIframe || !previewIframeLoaded || !target) {
			throw new Error('App preview is not ready')
		}
		// Collapsing the preview leaves the iframe mounted and populated at zero
		// width, which passes every check above and then fails inside the rasteriser
		// as an opaque decode error. Name the cause so the agent can act on it.
		if (!target.clientWidth || !target.clientHeight) {
			throw new Error(
				'The app preview is collapsed, so there is nothing to capture. Ask the user to expand the preview panel, then try again.'
			)
		}
		const { domToPng } = await import('modern-screenshot')
		// Above CSS resolution for small previews (a 1× capture of a ~900px preview
		// reads blurry next to the live render), sub-1× for oversized bodies — see
		// captureScale. maximumCanvasSize is the belt over that math: the rasterised
		// box can exceed the body's client size, and an unbounded canvas on a tall
		// scrolling app can freeze the tab before normalize ever bounds the pixels.
		const scale = captureScale(Math.max(target.clientWidth, target.clientHeight))
		const restore = pinSingleLineText(target)
		try {

View on GitHub (pinned to e474e8803c)

Solutions

1. Wait for the preview iframe to finish loading, then retry the screenshot
2. Ensure the preview pane is expanded (zero-size iframes fail downstream) and rendered
3. Reload the app editor and retry once the preview is visibly rendered
4. If it persists, check that the preview iframe is not blocked (browser extensions/iframe security)
5. Retry with a small delay after app deploy so the preview has time to mount

const ready = !!previewIframe?.contentDocument?.body && previewIframeLoaded
if (!ready) { await waitForPreviewLoad(5000) }

function isPreviewReady(iframe: HTMLIFrameElement | null, loaded: boolean): boolean {
  return !!iframe && loaded && !!iframe.contentDocument?.body
}

try {
  await captureScreenshot()
} catch (e) {
  if (e.message === 'App preview is not ready') {
    await waitForEvent(previewLoaded, 10000)
    await captureScreenshot()
  }
}

When it happens

Trigger: Requesting a screenshot (e.g. an AI/agent screenshot step) while the preview iframe is still loading, the iframe element is unmounted, or contentDocument.body is null (cross-origin/blocked document or very early load).

Common situations: Agent automation triggering screenshot immediately after deploy before the preview finishes loading; preview collapsed or hidden at mount time; slow app load (heavy queries) racing the screenshot request.

Related errors

• errorMsg ?? 'Job failed'
• Job was cancelled
• ${timeoutMessage}
• The app preview is collapsed, so there is nothing to capture
• writer close task panicked: {e}

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/127fb4fca16b8c05. Report an issue: GitHub.