Skip to content

Wait for a lagging Cloudflare Worker version list during deploy - #892

Open
konaito wants to merge 1 commit into
voidzero-dev:mainfrom
konaito:fix/retry-stale-cloudflare-version-history
Open

konaito wants to merge 1 commit into
voidzero-dev:mainfrom
konaito:fix/retry-stale-cloudflare-version-history

Conversation

@konaito

@konaito konaito commented Nov 21, 2026 •

Copy link
Copy Markdown

Fixes #891 for the version-list paths. The triggers-failed case in the issue is not changed here.

Change

Cloudflare's Worker version list can trail a write by minutes. The deploy now waits for it in the two places where the expected state is known:

  • Before the upload: while the list does not contain the active version that deployments status reported. This read had no retry.
  • After the upload: while the list is still identical to the pre-upload baseline. The existing retry stopped after 250 ms and 500 ms.

Both use STALE_VERSION_HISTORY_DELAYS_MS: 250 ms doubling up to 30 s, 17 waits, about 5.5 minutes in total. Each wait checks verifyUploader() and the first one reports progress. The schedule can be overridden with the new versionHistoryRetryDelaysMs option.

Why this length: in the runs in #891 a new version was still missing 52 s after creation and was listed within about 4.5 minutes. #880 and #868 retried for a second or less, which does not reach that. If maintainers want a shorter cap, change the constant.

What does not change

  • A list that never catches up still fails with the same reasons (inheritance-source-changed before the upload, inheritance-source-unavailable after it). Nothing is uploaded when the pre-upload wait runs out.
  • Any other mismatch (a concurrent version, a different history) still fails at once, with no wait.
  • A failed (not stale) read after the upload keeps its two quick retries.
  • A rollback to a version older than the list's page of 10 also never appears in the list. It now waits the full schedule before failing with the same reason as before.
  • stabilizeCloudflareVersionTriggers is untouched. The logs in Cloudflare deploy stops on a lagging Worker version list (inheritance-source-changed, triggers-failed) #891 do not show what its reads returned.

Tests

packages/deploy-cloudflare/test/unit/version.test.ts:

  • Pre-upload: active version present (no wait), list recovers after two stale reads, list never catches up (no upload), uploader changes during the wait.
  • Post-upload: the existing stale-list cases now expect the full schedule; failed reads still expect two waits.
  • The default schedule is used, is between 5 and 6 minutes, and reports progress.

The new pre-upload tests and the changed stale-list case fail on main and pass here (5 failures without the change).

Verified locally

Run in a shell with no CLOUDFLARE_*, CF_* or wrangler variables (env | grep -ciE 'cloudflare|^CF_|wrangler' printed 0). The tests inject runWrangler, so no cf or wrangler process starts.

  • vp test run packages/deploy-cloudflare/test/unit/version.test.ts: 231 passed
  • vp check: no warnings, lint errors or type errors
  • vp run check:types: 35/35 successful
  • vp run test:all: 92 of 93 tasks passed. The one failing task was platform-api-integration-threads, 12 tests, because Playwright's Chromium was not installed. After playwright install chromium the six failing files passed (204 tests).
  • No user-facing documentation changes: this is an internal retry window.

Cloudflare's Worker version list can trail a write by minutes. Before the
upload, wait while the list lacks the active version. After the upload, wait
while the list still equals the baseline, on a schedule of about 5.5 minutes
instead of 250 ms and 500 ms. Failed reads keep their two quick retries.

Refs voidzero-dev#891

@0froq 0froq left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looked into this and commented

for (
let attempt = 0;
previous.versionId !== null &&
recent !== null &&

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The waits only continue while the read succeeded. A versions.list whose two pages disagree returns a non-zero status, which readRecentCloudflareVersionIds turns into null. That case gets 0 waits before the upload and only the 250/500 ms retries after it. Page 2 is only read above 10 versions, so this is the shape of the 20:08 inheritance-source-unavailable report in #891, not the stale-but-readable shape this fixes.

Not a regression, but "Fixes #891 for the version-list paths" would close the issue with that symptom unchanged. Either classify the page-overlap failure and retry it on this schedule, or narrow the claim.

* Waits between reads of Cloudflare's Worker version list while it lags behind a write.
* Defaults to {@link STALE_VERSION_HISTORY_DELAYS_MS}.
*/
versionHistoryRetryDelaysMs?: ReadonlyArray<number>;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

STALE_VERSION_HISTORY_DELAYS_MS is this option's documented default but is not exported from src/index.ts, so a caller that wants to extend the schedule has to copy the array. Add it to the ./version.ts export list next to activateCloudflareVersion.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cloudflare deploy stops on a lagging Worker version list (inheritance-source-changed, triggers-failed)

2 participants