`createBackup()` wakes a container that stops after a running-state check

[alexminza]

Describe the bug

A container can stop after sandbox.getState() reports it as running but before sandbox.createBackup() is called. Because createBackup() automatically starts stopped containers, this race wakes the container and performs a backup that the caller intended to run only while it was already active.

There is no atomic non-waking backup operation equivalent to the established fetchIfRunning() pattern.

To Reproduce

1. Configure backup support, start a sandbox, and wait until it is running.
2. Call sandbox.getState() and observe running or healthy.
3. Stop the container after that state read, representing sleep, eviction, or a crash between the check and the operation.
4. Call sandbox.createBackup({ dir: "/workspace" }).
5. Observe that the backup starts the stopped container instead of reporting that it is no longer running.

Expected behavior

Add createBackupIfRunning() as the non-waking counterpart to createBackup(). It should atomically refuse to start a stopped container and return a typed not-running result or error. An equivalent createBackup() option would also solve the gap if maintainers prefer that API shape; the existing auto-start behavior can remain the default.

Screenshots

Not applicable.

• Version: @cloudflare/sandbox@0.12.1; source behavior reverified in the latest stable @cloudflare/sandbox@0.12.3.

Additional context

The practical impact is low but real: a periodic maintenance consumer can cause an unintended cold start and billed runtime. A state precheck plus an activity-window attempt marker bounds the observed consumer to one unintended wake per activity window, but cannot eliminate the race.

At stable tag @cloudflare/sandbox@0.12.3, BaseTransport.httpFetch() routes requests through containerFetch(), while Sandbox.containerFetch() starts the container when it is not running and healthy.

Related upstream work:

• sandbox-sdk#415 is the direct predecessor: it requested disabling auto-start for proxyToSandbox(), and maintainers confirmed that request-driven restart is intentional. This request is narrower and not a duplicate because scheduled backup must address the same sandbox and needs an atomic per-operation policy rather than alternate routing.
• containers#212 proposed fetchIfRunning() as a non-waking primitive. It was closed after sandbox-sdk#708 implemented the same scoped behavior inside the Sandbox SDK for preview URLs. createBackupIfRunning() applies that established naming and behavior to backups.
• Active sandbox-sdk#819 makes process discovery non-waking. That can remove the need for an exec() readiness probe once released, but createBackup() still has no already-running-only mode.
• Active containers#148 documents the underlying stop race and intentionally restarts the container when a request arrives while it is stopping. This is why a separate state check cannot provide the requested guarantee.

I searched open and closed issues and pull requests in both repositories for no-wake, no-auto-start, stopped-container, containerFetch, exec, and backup variants. Neither repository has GitHub Discussions enabled.

[scuffi]

@agent-think hey can you reproduce this issue

[agent-think]

Requested by @scuffi

Verdict: reproduced ✅

@cloudflare/sandbox@0.12.3 wakes the sandbox after a successful running-state read if the container stops before createBackup(). I reproduced the exact healthy → stopped → createBackup() → healthy sequence; the backup succeeded and the startup path was called once.

Repro URL (expires after 60 mins): https://sandbox-backup-wake-repro-825.sustaining-allosaurus.workers.dev

Open it, press Trigger bug, and watch the status/log show the state transition and backup result.

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

Minimal repro

Key configuration:

// wrangler.jsonc
{
  "name": "sandbox-backup-wake-repro-825",
  "main": "src/server.ts",
  "compatibility_date": "2026-07-20",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]
  },
  "durable_objects": {
    "bindings": [{ "name": "Sandbox", "class_name": "Sandbox" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Sandbox"] }]
}

Core sequence (the branch contains the complete runnable Worker/UI):

await mockContainerBoundary.resetMockRuntime("healthy");
const stateReadBeforeStop = await sandbox.getState(); // healthy
await sandbox.stop();
const stateAfterStop = await sandbox.getState();      // stopped

// Real, unmodified @cloudflare/sandbox@0.12.3 implementation:
const backup = await sandbox.createBackup({
  dir: "/workspace",
  localBucket: true,
  multipart: false
});

const stateAfterBackup = await sandbox.getState();    // healthy

Temporary preview accounts currently reject Container-application creation with 403 Forbidden and do not expose R2. The live page therefore runs the unmodified SDK 0.12.3 Sandbox class, while aliasing only the unavailable @cloudflare/containers platform boundary and supplying an in-memory structural R2 bucket. The boundary deterministically models the reported stop race and records startup calls. I separately ran a source-level Vitest repro against the exact @cloudflare/sandbox@0.12.3 git tag (696388b); it passed with the same behavior (1 test passed).

Observed vs expected

Live endpoint output (abridged):

{
  "reproduced": true,
  "sequence": {
    "stateReadBeforeStop": { "status": "healthy" },
    "stateAfterStop": { "status": "stopped" },
    "backup": {
      "id": "f405a9de-d338-4924-aa78-29faf9cd51d3",
      "dir": "/workspace",
      "localBucket": true
    },
    "stateAfterBackup": { "status": "healthy" },
    "startupCalls": 1,
    "containerApiRequests": [
      "/api/session/create",
      "/api/backup/create",
      "/api/read/stream",
      "/api/execute",
      "/api/session/delete"
    ]
  }
}

Expected: an atomic already-running-only backup should reject once stopped and leave the container stopped. Actual: createBackup() invoked startup, completed, and left it healthy.

Root-cause hypothesis

At the 0.12.3 tag:

1. createBackup() enters doCreateBackupLocal(); its first container operation is ensureBackupSession() (packages/sandbox/src/sandbox.ts:5976-5979, called at :6849).
2. UtilityClient.createSession() goes through BaseTransport.httpFetch().
3. BaseTransport.httpFetch() always calls stub.containerFetch() (packages/sandbox/src/clients/transport/base-transport.ts:112-119).
4. Sandbox.containerFetch() explicitly checks state and calls startAndWaitForPorts() whenever it is not healthy/running (packages/sandbox/src/sandbox.ts:3023-3053).

There is no no-wake policy propagated through the backup client/transport, and a separate getState() check cannot close this race. A createBackupIfRunning() API (or equivalent option) needs an atomic non-waking transport path for every container call in the backup operation, analogous to the established already-running-only forwarding behavior.

🤖 generated by the repro-agent

[aron-cf]

Hey @alexminza I'm inclined to close this as a wontfix at the moment. I see the race condition you've illustrated. There is a native container snapshotting implementation in the works that will replace this API entirely so I'm inclined to defer to that as the correct fix here.

In the mean time if you want to improve the robustness of the existing implementation you could also consider using the sync ctx.container.running check rather than getState() to remove one of the async steps and putting the conditional check in the Sandbox class rather than calling from a worker.

I'm very happy to reopen or continue discussing this if you have further thoughts.