STALE_PREVIEW_URL on every preview request despite healthy container (0.11.0)

[omararambula]

Summary

sandbox.exposePort() succeeds (its assertActive(runtime) passes), but every request to the returned preview URL returns 410 STALE_PREVIEW_URL ("Preview URL is stale because the sandbox runtime is not active") — even while the same sandbox's container is verifiably healthy and serving traffic.

Environment

• @cloudflare/sandbox 0.11.0 (worker-side and DO)
• Container image: cloudflare/sandbox:0.11.0-desktop
• Worker deployed with a wildcard route (*.example.com/*) + run_worker_first: true; proxyToSandbox middleware intercepts preview hostnames
• Sandbox accessed via getSandbox(env.Sandbox, taskId) (also tried { keepAlive: true })

Repro

1. Custom domain worker; wildcard DNS exists and TLS is valid (one level under the zone apex).
2. const sandbox = getSandbox(env.Sandbox, id);
3. const { url } = await sandbox.exposePort(6080, { hostname: "example.com" }) → returns https://6080-<id>-<token>.example.com/ (HTTP 200).
4. GET <url>vnc.html → 410 {"error":"Preview URL is stale because the sandbox runtime is not active","code":"STALE_PREVIEW_URL"}.

The stale response persists for 4+ minutes of polling and across repeated exposePort() re-registrations (same token returned each time). keepAlive: true does not change it.

Expected

Preview URL forwards to the container port once the container is running.

Notes

• The same sandbox executes commands fine via exec (container boots, agent responds), so the runtime is active in practice.
• From reading the DO code, fetchPreviewIfRunning returns stale when !container?.running || state.status !== "healthy" or !currentRuntime.isActive(runtime). Since exposePort()'s assertActive(runtime) passes, the registration-side state disagrees with the proxy-side state somewhere (possibly a runtime-id mismatch after DO migration/restart, or the health gate never reaching healthy on the desktop image).
• Same behavior with the SDK's getDesktopStreamUrl(hostname) convenience on the desktop image.
• Happy to provide a minimal repro repo if useful.

[aron-cf]

@agent-think can you create a reproduction of this issue please.

[agent-think]

Requested by @aron-cf

Verdict: could not reproduce the reported STALE_PREVIEW_URL

I built a minimal Vite UI + Worker around the exact @cloudflare/sandbox@0.11.0 package and cloudflare/sandbox:0.11.0-desktop image. In local workerd/Containers execution the sandbox was healthy, noVNC answered on port 6080, exposePort() succeeded, and all 3 preview requests returned HTTP 200 noVNC HTML, not 410 STALE_PREVIEW_URL.

Repro URL (expires after 60 mins): https://repro-829-stale-preview-url.sincere-calf.workers.dev

Open it, press Trigger bug, and watch the log. Temporary preview accounts cannot provision Containers, so this hosted UI currently demonstrates that platform limitation (the trigger ends with a container-start error); pull the branch below and deploy it on a Containers-enabled account for the production check.

Repro branch: https://github.com/cloudflare/sandbox-sdk/tree/repro/issue-829 — pull this branch to run the repro yourself.

Minimal repro

Dockerfile
index.html
src/client.tsx
src/server.ts
vite.config.ts
wrangler.jsonc

FROM docker.io/cloudflare/sandbox:0.11.0-desktop

{
  "main": "src/server.ts",
  "compatibility_date": "2026-07-22",
  "compatibility_flags": ["nodejs_compat"],
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "basic",
    "max_instances": 1
  }],
  "durable_objects": {
    "bindings": [{ "name": "Sandbox", "class_name": "Sandbox" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Sandbox"] }]
}

The worker's trigger is intentionally small:

const sandbox = getSandbox(env.Sandbox, "repro829", { keepAlive: true });
const exec = await sandbox.exec("printf container-exec-healthy");
await sandbox.desktop.start({ resolution: [1024, 768] });
const portCheck = await sandbox.exec(
  "curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:6080/vnc.html"
);
const exposed = await sandbox.exposePort(6080, {
  hostname: "repro.invalid",
  token: "repro829"
});

for (let attempt = 1; attempt <= 3; attempt++) {
  const request = new Request(new URL("/vnc.html", exposed.url));
  const response = await proxyToSandbox(request, env);
  // record response.status + response body
}

repro.invalid only removes wildcard DNS/TLS setup from the harness: the generated request still traverses proxyToSandbox() → Sandbox Durable Object → preview auth/runtime validation → container port forwarding.

What I observed

{
  "containerHealthy": true,
  "exec": { "success": true, "exitCode": 0, "stdout": "container-exec-healthy" },
  "desktopStatus": "active",
  "port6080FromContainer": { "success": true, "httpStatus": "200" },
  "exposePort": { "url": "https://6080-repro829-repro829.repro.invalid/", "port": 6080 },
  "previewStatuses": [200, 200, 200]
}

Each preview body began with noVNC's <!DOCTYPE html><html class="noVNC_loading">. Expected per the report was [410, 410, 410] with {"code":"STALE_PREVIEW_URL"}.

The required build passed (vite build). The hosted root returns HTTP 200. A full temporary deploy cannot roll out a Container because the temporary-account Containers API returns 403 Forbidden; I therefore published the UI with --containers-rollout=none and did the actual container-path verification locally.

Root-cause hypothesis

This looks production/platform-lifecycle-specific rather than a deterministic desktop-image or preview-routing failure. The suspect gate remains packages/sandbox/src/sandbox.ts in validatePreviewURLForRuntime() / fetchPreviewIfRunning(), which returns stale when the Containers state is not healthy, ctx.container.running is false, or the stored runtime/activation identities disagree.

One concrete version interaction is worth checking: @cloudflare/sandbox@0.11.0 declares @cloudflare/containers: ^0.3.5, but the repository's 0.11.0 lockfile used 0.3.5. Containers 0.3.7 later shipped a fix described as “Prevent startup and stop handling races from persisting a stopped state for a running container.” An application installing 0.11.0 without a lock can resolve 0.3.7, while a locked deployment may remain on 0.3.5. That race could make preview validation see stale lifecycle state even while control-plane calls still reach a healthy container. I tested both 0.3.5 and the latest compatible 0.3.7 locally; both returned 200, so this is a hypothesis, not a confirmed cause.

🤖 generated by the repro-agent