agent timed out waiting for the pages build queue: preview build stalled for 30 minutes

TL;DR

Pages preview builds queue behind other builds, and at peak times the queue stalls. The agent waits for a build that has not started. Check the build status (queued vs building vs failed), set a bounded wait with status checks, and have a fallback (direct upload deploy) when the queue is the blocker.

The query

agent timed out waiting for the pages build queue: preview build stalled for 30 minutes

Use this when

• The Pages build shows 'queued' for a long time.
• The agent polls waiting for the preview URL.
• Production builds are fine but previews stall (or vice versa).

Not for

• Builds that start and then fail (fix the build).
• '_worker.js exceeds the size limit' (bundle problem, separate fix).
• The preview URL 404ing after a successful build (routing problem).

Steps

Step 1: Check the actual build state

Look at the deployment in the dashboard: queued, building, failed, or successful-but-unnoticed.

Expected result: the true state. 'Queued for 30 minutes' is a queue problem; 'failed in 2 minutes but the agent kept polling' is a polling bug.

Step 2: Fix the polling bug if the build already finished

The agent should poll the deployment status API, not the preview URL, and stop on terminal states (success, failure, canceled).

Expected result: the agent learns the outcome in seconds instead of timing out after 30 minutes.

Step 3: For genuine queue stalls, wait bounded and escalate

Wait with periodic status checks up to a documented limit (e.g. 20 minutes), then escalate: notify, retry the build, or fall back.

Expected result: the agent never hangs indefinitely. A stalled queue becomes a reported incident, not a silent timeout.

Step 4: Use direct upload as the fallback

wrangler pages deploy with a prebuilt output directory skips the Pages build queue entirely.

Expected result: previews unblock even when the build service is backed up. The agent has a second path.

Step 5: Reduce queue pressure structurally

Smaller builds queue less and build faster. Trim the build, cache dependencies, and avoid rebuilding unchanged assets.

Expected result: fewer and shorter queue waits. The 30-minute stall becomes rare instead of routine.

Why it happens

Build queues are shared resources with variable wait times. Agents treat 'triggered' as 'will complete soon' and poll the wrong signal (the URL) instead of the right one (the deployment status). The combination turns a 30-minute queue into a 30-minute mystery.

Edge cases

• Preview builds and production builds may use different queues or limits. Compare like with like.
• A build stuck in 'building' (not 'queued') for 30 minutes is a hung build, not a queue stall. Cancel and investigate.
• Retrying the build re-queues at the back. One patient wait beats five impatient retries.
• Build timeouts kill long builds; distinguish 'timed out by the platform' from 'still queued'.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9qbQfUGVUubjT4kw7Jtnxw